dita open toolkit 2 - documentation.help · the dita open toolkit (dita-ot) is an open-source...
TRANSCRIPT
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
Toolkitdocumentation
Therearetwoprimarysourcesfordocumentationaboutthetoolkit.
Stabledocumentationabouttoolkitusage,parameters,andprojectmanagementcanbefoundonthispage,usingthenavigationpanelontheleft.
Newinformationaboutthelatesttoolkitbuilds,plansforthenextrelease,andotherchanginginformationcanbefoundontheDITA-OTlandingpageatthedita.xml.orgsite(linkbelow).Thatsitealsocontainsthereleasenotesforallupcomingandpreviousreleases.
RelatedconceptsDistributionpackages
RelatedinformationMainDITA-OTpageatdita.xml.orgProjectNewsforDITAOpenToolkit
ShortcutstoimportantinformationDITA-OTstablereleaseDITA-OTlatestdevelopmentbuild
GettingStartedwiththeDITAOpenToolkitTheGettingStartedGuideisdesignedtoprovideaguidedexplorationoftheDITAOpenToolkit.ItisgearedforanaudiencethathaslittleornoknowledgeofbuildscriptsorDITA-OTparameters.Itwalksthenoviceuserthroughinstallingthefull-easy-installversionofthetoolkitandrunningapromptedbuild.
1. Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
2. RunningthedemobuildAfteryouinstallthefull-easy-installpackage,runthedemobuildtoseethetypeofoutputthatisproducedbytheDITAOpenToolkit.
3. BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.
Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
Beforeyoubegin
EnsurethatyouhaveJavaJREorJDK,version7orlaterinstalled.
EnsurethatyouhaveHTMLHelpWorkshopinstalled,ifyouwanttogenerateHTMLHelp.
Procedure
1. Downloadthefull-easypackagefromSourceForge.
Operatingsystem Filename
LinuxorMacOSX
DITA-OT2.0.M3_full_easy_install_bin.tar.gz
Windows DITA-OT2.0.M3_full_easy_install_bin.zip
2. ExtractthecontentsofthepackagetothedirectorywhereyouwanttoinstalltheDITA-OT.
3. Runthestartcmdfilethatisapplicableforyouroperatingsystem.ThisdefinesthenecessaryenvironmentvariablesandopensaDOSpromptorterminalwindowinwhichyoucaninvokethetoolkit.Youcanusethewindowtorunasmanybuildsasyouwant;ifyouclosethewindow,youwillneedtoruntheapplicablestartcmdfileagain.
Parenttopic:GettingStartedwiththeDITAOpenToolkitNexttopic:Runningthedemobuild
RunningthedemobuildAfteryouinstallthefull-easy-installpackage,runthedemobuildtoseethetypeofoutputthatisproducedbytheDITAOpenToolkit.
Procedure
1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.
2. FromtheDITA-OTshell,enterthefollowingcommand:
ant-fbuild_demo.xml
Youreceivethefollowingprompt:
[echo]PleaseenterthefilenamefortheDITAmapthatyou
[echo]wanttobuildincludingthedirectorypath(ifany).
[echo]Thefilenamemusthavethe.ditamapextension.
[echo]Notethatrelativepathsthatclimb(..)arenotsupportedyet.
[echo]Tobuildthesample,pressreturnwithoutenteringanything.
[input]TheDITAmapfilename:[C:\DITA-OT2.0.M3\samples\hierarchy.ditamap]
3. PressEnter.Youreceivethefollowingprompt:
[echo]
[echo]Pleaseenterthenameoftheoutputdirectoryorpressreturn
[echo]toacceptthedefault.
[input]Theoutputdirectory(out):[out]
4. PressEnter.Youreceivethefollowingprompt:
[echo]Pleaseenterthetypeofoutputtogenerate.
[echo]Optionsinclude:eclipse,tocjs,htmlhelp,javahelp,pdf,orweb
[echo]Uselowercaseletters.
[echo]
[input]Theoutputtype:(eclipse,tocjs,htmlhelp,javahelp,pdf,[web],docbook)
5. PressEntertoacceptthedefaulttransformationtype:web.ThiswillbuildXHTMLfilesfromtheDITAsource.
Youreceivethefollowingprompt:
[echo]ReadytobuildC:\DITA-OT2.0.M3\samples\hierarchy.ditamap
[echo]forwebinout
[echo]
[input]Continue?(Y,[y],N,n)
6. PressYorytostarttheDITA-OTtransformation.TheDITA-OTlogsinformationtothecommand-promptorterminalwindow.Attheend,youseethefollowinginformation:
prompt.output:
[echo]
[echo]outputintheoutdirectory
[echo]
[echo]Beforerebuilding,pleasedeletetheoutputorthedirectory.
BUILDSUCCESSFULTotaltime:XminutesXseconds
7. Gototheout/directoryandopenthetoc.htmlfileinaWebbrowser.Figure1.XHTMLoutputforthesamplefiles
Results
TheDITA-OTtransformedthehierarchy.ditamapfile(locatedinthesamplesdirectory)toXHTML;itwrotetheoutputtotheout/directory.
Parenttopic:GettingStartedwiththeDITAOpenToolkitPrevioustopic:Installingthefull-easy-installpackageNexttopic:Buildingyourowncontentusingthedemobuild
BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.
Procedure
1. Ifnecessary,runthestartcmdfilethatisapplicableforyouroperatingsystem.Youdonotneedtorunthestartcmdfileifyoualreadyhaveacommand-promptorterminalwindowthatwasinvokedbythestartcmdfileopen.
2. FromtheDITA-OTshell,enterthefollowingcommand:
ant-fbuild_demo.xml
3. Whenprompted,typethenameofamap.YoumustspecifythepathfortheDITAmap.Youeithercanspecifyafullyqualifiedfilename,forexample,C:\DITA-OT1.6.M5\doc\userguide.ditamap,oryoucanspecifyarelativepath,forexample,doc\userguide.ditamap
4. Whenprompted,typethenameoftheoutputdirectory.
5. Whenprompted,typethevalueforthetransformationtype.
Ouputformat ValueDocbook docbookEclipsehelp eclipseHTMLhelp htmlhelpPDF pdfXHTML webXHTMLwithaJavaScriptframeset tocjs
6. Whenprompted,pressEntertostartthetransformation.
Results
TheDITA-OTgeneratesoutputforthespecifiedDITAcontent.Itrunsthetransformationthatyouspecified,andwritestheoutputtothedirectorythatyouspecified.
Whattodonext
ExploreinvokingtheDITA-OTfromeitherAntorthecommand-linetool.Thisenablesyoutospecifyawiderarrayofparametersthanthosesupportedbythedemobuild.
UsingAntorthecommand-linetool,youcanperformthefollowingtasks(andmore):
AddacustomCSSfiletothetransformation
Generatelabelsforthesectionsoftasktopics
Specifythatdraftcommentsareincludedintheoutput
Turnon"Relatedlink"sectionsinaPDFfile
Parenttopic:GettingStartedwiththeDITAOpenToolkitPrevioustopic:Runningthedemobuild
DITAOpenToolkitUserGuideTheDITAOpenToolkitUserGuideisdesignedtoprovidebasicinformationabouttheDITA-OT.Itisgearedforanaudiencethatneedsinformationaboutinstalling,running,andtroubleshootingthetoolkit.ItcontainsdocumentationoftheDITA-OTparameters;italsocontainsreleasenotesandinformationaboutwhatcomponentshavebeentested.
OverviewoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISDITAspecification,whichisdevelopedbytheOASISDITATechnicalCommittee.TheDITA-OTisasetofJava-based,open-sourcetoolsandAntscriptsthattransformDITAcontent(mapsandtopics)intodeliverableformats,includingEclipseHelp,HTMLHelp,JavaHelp,PDF,andXHTML.
InstallingtheDITAOpenToolkitYoucaninstalltheDITAOpenToolkit(DITA-OT)onLinux,MacOSX,andWindows.TheprocessforinstallingandsettinguptheDITA-OTdependsonthetypeofdistributionpackagethatyouselect.
PublishingDITAcontentYoucanuseeitherAntorthecommand-linetooltotransformDITAcontenttothevariousoutputformatsthataresupportedbytheDITAOpenToolkit(DITA-OT).
ExtendingtheDITAOpenToolkitPlug-inscanbeusedtoextendthefunctionalityandconfiguretheDITAOpenToolkit.
GlobalizingDITAcontentTheDITAstandardsupportscontentthatiswritteninortranslatedtoanylanguage.Ingeneral,theDITAOpenToolkit(DITA-OT)passescontentthroughtotheoutputformatunchanged.TheDITA-OTusesthevaluesforthe@xml:lang,@translate,and@dirattributesthataresetinthesourcecontenttoprovidesglobalizationsupport.
ErrormessagesandtroubleshootingThissectioncontainsinformationaboutproblemsthatyoumightencounterandhowtoresolvethem.
ReferenceThissectionisdesignedtohelpuserstolocateinformationeasilyandquickly.ItincludesdocumentationfortheDITAOpenToolkit(DITA-OT)parametersandconfigurationproperties.
OverviewoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISDITAspecification,whichisdevelopedbytheOASISDITATechnicalCommittee.TheDITA-OTisasetofJava-based,open-sourcetoolsandAntscriptsthattransformDITAcontent(mapsandtopics)intodeliverableformats,includingEclipseHelp,HTMLHelp,JavaHelp,PDF,andXHTML.
WhiletheDITAstandardisownedanddevelopedbyOASIS,theDITA-OTprojectisgovernedseparately;theDITA-OTisanindependent,open-sourceimplementationoftheDITAstandard.TheDITA-OTisavailablewithoutchargeandislicensedundertheCPL1.0andApache2.0open-sourcelicenses.
DITAOpenToolkitRelease2.0
DITA1.2SpecificationSupportDITAOpenToolkit2.0supportstheDITA1.2specification.Initialsupportforthisspecificationwasaddedinversion1.5ofthetoolkit;versions1.5.1and1.5.2containminormodificationstokeepupwiththelatestdrafts.ThespecificationitselfwasapprovedatapproximatelythesametimeasDITA-OT1.5.2,whichcontainedthefinalversionsoftheDTDandSchemas.DITA-OT1.6updatedtheDITA1.2XSDstoaddressminorerratainthestandard;theDTDsremainuptodate.
TestedplatformsandtoolsTheDITAOpenToolkit(DITA-OT)hasbeentestedagainstcertainversionsofAnt,ICUforJava,JDK,operatingsystems,XMLparsers,andXSLTprocessors.
Parenttopic:DITAOpenToolkitUserGuide
RelatedinformationCommonPublicLicense,version1.0ApacheLicense,version2.0
DITAOpenToolkitRelease2.0Parenttopic:OverviewoftheDITAOpenToolkit
GeneralEnhancementsandChanges
Migrationfrompreviousreleases
Issues
ThefollowingitemsareincludedinDITAOpenToolkitRelease2.0.IssuenumberscorrespondtothetrackingnumberintheGitHubissuestracker.
Featurerequests
#1192Empty<ul></ul>killsFOP(milestone1)
#1267PDFsupportforfigurelink/tablelink.style(milestone1)
#1347Issuewith"xsl/dita2xhtml.xsl"?(milestone1)
#1506Newcommandlinetool(milestone1)
#1507ConvertXSLTtoversion2.0(milestone1)
#1511UseIvyfordependencymanagement(milestone1)
#1522AddHTML5transtype(milestone1)
#1523ReduceHTML/XHTMLcodeduplication(milestone1)
#1524UseDITAVALforprintfiltering(milestone1)
#1548SupportRFC5147incoderef(milestone1)
#1561Combinechunkedtopiclistsintofullditatopiclist(milestone1)
#1569IndexcapabilitywithFOP(milestone1)
#1601ChangeoutputforrenderingasingletopictoPDF(milestone1)
#1602Addplug-ininstallationoperationtointegration(milestone1)
#1608imgshouldbeusedinsteadofembedinXHTMLoutputforallimagetypes(milestone1)
#1610FilteredcontentleadstototalfailofPDFrenderingduplicate(milestone1)
#1612UpdateAntto1.9.2(milestone1)
#1614antbuildshouldnotbailoutwhenfopdirectoryhasnolibfolder(milestone1)
#1616RemovelegacyPDFfromdefaultdistributions(milestone1)
#1509Removedeprecatedcode(inprogress)
#1649SupportDITA1.3linksyntax(milestone2)
#1644AddmoreHTMLentitiestofileentities.propertiesindost.jar(milestone2)
#1643Integratortaskconstructspropertyconstructswithplatform-dependentpathseparators(milestone2)
#1636SupportDITA1.3cascadeattribute(milestone2)
#1635ImplementDITA1.3profiling(milestone2)
#1631Processkeyrefsbeforeconref(milestone2)
#1673Removesupportforgenerate.copy.outer=2(milestone3)
#1671AddsupportforgeneratingbackcoveronPDF(milestone3)
#1667RemoveFrameMakerindexsyntaxsupport(milestone3)
#1512Alternativepreprocessingplug-in(inprogress)
#1544UseURIandFileinsteadofString(inprogress)
#1654AddDITA1.3divelement(inprogress)
#1652AddDITA1.3markupandxmldomainsupport(inprogress)
#1651AddnewDITA1.3highlightingelements(inprogress)
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
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.
Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
Parenttopic:DITAOpenToolkitUserGuide
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:
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.8
ApacheXerces,version2.11.0
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
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.8
ApacheFOP,version1.1
ICUforJava,version52.1
ApacheXerces,version2.11.0
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
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.8
ApacheFOP,version1.1
ICUforJava,version52.1
ApacheXerces,version2.11.0
Saxon,version9.1.0.8
Thefull-easy-installpackagehasthefollowingfilenames:
DITA-OT2.0.M3_full_easy_install_bin.zip
DITA-OT2.0.M3_full_easy_install_bin.tar.gz
Parenttopic:InstallingtheDITAOpenToolkit
RelatedinformationDITAOpenToolkitdistibutionpackagedownloadsDITAOpenToolkitsource
PrerequisitesoftwareTheprerequisitesoftwarethattheDITA-OTrequiresdependsonthetypeofdistributionpackagethatyouintendtoinstallandthetypesoftransformationsthatyouwanttouse.
SoftwarerequiredforcoreDITA-OTprocessing
TheDITA-OTrequiresthefollowingsoftwareapplications:
JREorJDK,version7orlater
ProvidesthebasicenvironmentfortheDITA-OT.YoucandownloadtheOracleJREorJDKfromhttp://www.oracle.com/technetwork/java/javase/downloads/index.htmlIfyouopttousethefull-easy-installpackage,thisistheonlyprerequisitesoftwarethatyouneedtoinstall.
Ant,version1.7.1orlater
Providesthestandardsetupandsequencingofprocessingsteps.YoucandownloadAntfromhttp://ant.apache.org/.
XSLTprocessor
Providesthemaintransformationservices.ItmustbecompliantwithXSLT2.0.TheDITA-OTistestedwithSaxon.YoucandownloadSaxon,version9.1.0.8fromhttp://saxon.sourceforge.net/.
Softwarerequiredforspecifictransformations
Dependingonthetypeofoutputthatyouwanttogenerate,youmightneedthefollowingapplications:
ICUforJava
ICUforJavaisacross-platform,Unicode-based,globalizationlibrary.Itincludessupportforcomparinglocale-sensitivestrings;formattingdates,times,numbers,currencies,andmessages;detectingtextboundaries;andconvertingcharactersets.YoucandownloadICUforJavafromhttp://www.icu-project.org/download/.
MicrosoftHelpWorkshop
RequiredforgeneratingHTMLhelp.YoucandownloadtheHelpWorkshopfromhttp://msdn.microsoft.com/en-us/library/windows/desktop/ms669985%28v=vs.85%29.aspx.
XSL-FOprocessor
RequiredforgeneratingPDFoutput.YoucandownloadFOPfromhttp://xmlgraphics.apache.org/fop/download.html;youalsocanuseAntennaHouseFormatterorRenderX.
SeeTestedplatformsandtoolsfordetailedinformationaboutversionsoftheprerequisiteapplicationsthathavebeentestedwiththecurrentDITA-OTrelease.
Parenttopic:InstallingtheDITAOpenToolkit
InstallingtheclientpackageForthesimplestinstallationexperience,installtheclientpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
Beforeyoubegin
EnsurethatyouhaveJavaJREorJDK,version7orlaterinstalled.
EnsurethatyouhaveHTMLHelpWorkshopinstalled,ifyouwanttogenerateHTMLHelp.
Procedure
1. DownloadtheclientpackagefromSourceForge.
Operatingsystem Filename
LinuxorMacOSX
DITA-OT2.0.M3_client_bin.tar.gz
Windows DITA-OT2.0.M3_client_bin.zip
2. ExtractthecontentsofthepackagetothedirectorywhereyouwanttoinstalltheDITA-OT.
3. Optional:AddbindirectorytoPATHsystemvariable.Thisdefinesthenecessaryenvironmentvariabletoruntheditacommandfromthecommand-line.
Parenttopic:InstallingtheDITAOpenToolkit
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:InstallingtheDITAOpenToolkit
InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
Beforeyoubegin
Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:
Ant,version1.7.1orlater
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
TocJS
TROFF
XHTML
Parenttopic:InstallingtheDITAOpenToolkit
InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
Beforeyoubegin
Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:
Ant,version1.7.1orlater
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
TocJS
TROFF
XHTML
Parenttopic:InstallingtheDITAOpenToolkit
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.
Parenttopic:DITAOpenToolkitUserGuide
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.
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:EclipsecontenttransformationCommand-linetoolparameters:Eclipsecontenttransformation
DITAtoEclipsehelpTheeclipsehelptransformationgeneratesXHTMLoutput,CSSfiles,andthecontrolfilesthatareneededforEclipsehelp.
InadditiontotheXHTMLoutputandCSSfiles,thistransformationreturnsthefollowingfiles,wheremapnameisthenameofthemasterDITAmap.
Filename Descriptionplugin.xml ControlfilefortheEclipseplug-inmapname.xml Tableofcontentsindex.xml Indexfileplugin.properties META-INF/MANIFEST.MF
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:EclipsehelptransformationCommand-linetoolparameters:Eclipsehelptransformation
RelatedinformationOfficialEclipseWebsite
DITAtoHTML5Thehtml5transformationgeneratesHTML5outputandatableofcontents(TOC)file.
TheHTML5outputisalwaysassociatedwiththedefaultDITA-OTCSSfile(commonltr.cssorcommonrtl.cssforright-to-leftlanguages).Youcanusetoolkitparameterstoaddacustomstylesheetstooverridethedefaultstyles.
ToruntheHTML5transformation,setthetranstypeparametertohtml5.
Parenttopic:DITA-OTtransformations
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.
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:HTMLHelptransformationCommand-linetoolparameters:HTMLhelptransformation
DITAtoOpenDocumentTypeTheodttransformationproducesoutputfilesthatusetheOpenDocumentformat,whichisusedbytoolssuchasOpenOffice.
ThistransformreturnsanODTdocument,whichisazipfilethatcontainstheODFXMLfile(content.xml),referencedimages,anddefaultstyling(inthefilestyles.xml).
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:ODTtransformationCommand-linetoolparameters:ODTtransformation
DITAtoPDF(PDF2)Thepdf(orpdf2)transformationgeneratesPDFoutput.
Thistransformationwasoriginallycreatedasaplug-inandmaintainedoutsideofthemaintoolkitcode.ItwascreatedasamorerobustalternativetothedemoPDFtransformationintheoriginaltoolkit,andthuswasknownasPDF2.Theplug-inwasbundledintothedefaulttoolkitdistributionwithrelease1.4.3.
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:PDFtransformationCommand-linetoolparameters:PDFtransformation
DITAtoRichTextFormatThewordrtftransformationproducesanRTFfileforusebyMicrosoftWord.
ThestructureofthegeneratedRTFfileisthesameasthenavigationstructureintheDITAmap.Toavoidlosingfilesinthefinaloutput,makesuretheDITAmapcontainsalltopicsthatarereferencedfromanyindividualtopics.
Thewordrtftransformationhasthefollowinglimitations:
Flagging,filtering,andrevisionbarsarenotsupported.
Styleattributesfortablesarenotsupported.
Tableswithinlistitemsarenotsupported.
OutputstylessupportedbyotherDITA-OTtransformations,forexample,XandY,arenotsupported.
Parenttopic:DITA-OTtransformations
DITAtoTocJSThetocjstransformationgeneratesHTML5output,aframeset,andaJavaScript-basedtableofcontentswithexpandableandcollapsibleentries.ThetransformationwasoriginallycreatedbyShawnMcKenzieasaplug-inandwasaddedtothedefaultdistributioninDITAOT,release1.5.4.
ThetocjstransformationwasupdatedsothatitproducesHTML5outputandusesadefaultframeset.Thistransformationalsowasaddedtothebuild_demo.xmlscriptasatransformation-typeoption.
Parenttopic:DITA-OTtransformations
DITAtoTroffThetrofftransformationproducesoutputforusewiththeTroffvieweronUnix-styleplatforms,particularlyforprogramssuchastheManpageviewer.
EachDITAtopicgenerallyproducesonetroffoutputfile.ThetrofftransformationsupportsmostcommonDITAstructures,butitdoesnotsupport<table>or<simpletable>elements.MosttestingoftroffoutputwasperformedusingtheCygwinLinuxemulator.
Parenttopic:DITA-OTtransformations
DITAtoXHTMLThexhtmltransformationgeneratesXHTMLoutputandatableofcontents(TOC)file.ThiswasthefirsttransformationcreatedfortheDITAOpenToolkit,anditisthebasisforalltheHTML-basedtransformations.
TheXHTMLoutputisalwaysassociatedwiththedefaultDITA-OTCSSfile(commonltr.cssorcommonrtl.cssforright-to-leftlanguages).Youcanusetoolkitparameterstoaddacustomstylesheetstooverridethedefaultstyles.
ToruntheXHTMLtransformation,setthetranstypeparametertoxhtml.Ifyouarerunningthedemobuild,specifywebratherthanxhtml.
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:HTML5andXHTMLtransformationCommand-linetoolparameters:HTML5andXHTMLtransformation
PublishingDITAcontentwithditacommandDITA-OTincludesaditacommand-linetool.YoucaninvoketheDITA-OTfromthecommand-linetoolandgenerateoutput.
BuildingoutputusingtheditacommandYoucaninvokeDITA-OTandbuildoutputusingtheditacommand.
Parenttopic:PublishingDITAcontent
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.
Parenttopic:PublishingDITAcontent
RelatedconceptsAnt
RelatedreferenceAntparameters
AntAntisaJava-based,open-sourcetoolthatisprovidedbytheApacheFoundation.Itcanbeusedtodeclareasequenceofbuildactions.Itiswellsuitedforbothdevelopmentanddocumentbuilds.Thefull-easy-installversionofthetoolkitshipswithacopyofAnt.
TheDITA-OTusesAnttomanagetheXSLTscriptsthatareusedtoperformthevarioustransformation;italsousesAnttomanageintermediatestepsthatarewritteninJava.
ThemostimportantAntscriptisthebuild.xmlfile.Thisscriptdefinesandcombinescommonpre-processingandoutputtransformationroutines;italsodefinestheDITA-OTextensionpoints.
Parenttopic:PublishingDITAcontentfromAnt
RelatedtasksBuildingoutputusingAntCreatinganAntbuildscriptPublishingDITAcontentfromAnt
RelatedreferenceAntparametersApacheAntdocumentation
BuildingoutputusingAntYoucanbuildoutputbyrunningtheantcommandandspecifyingtheDITA-OTparametersatthecommandprompt.YoualsocanuseanAntbuildscripttoprovidetheDITA-OTparameters
Procedure
1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.
2. ToprovidetheDITA-OTparametersfromthecommandprompt,issuethefollowingcommand:
ant-Dargs.input=input-file-Dtranstype=transformation-type-D
where:
input-fileistheDITAmaporDITAfilethatyouwanttoprocess.
transformation-typeisthetransformationtype.
parameter-nameisthenameofanoptionalparameter.
valueisanapplicablevaluefortheoptionalparameter.
Ifyoudonotspecifyanoutputdirectory,bydefault,theDITA-OTwritestheoutputtotheinstallation-directory\outdirectory.
3. Ifyouuseabuildscript,issuethefollowingcommand:
ant-fbuild-scripttarget
where:
build-scriptisnameoftheAntbuildscript.
targetisanoptionalswitchthatspecifiesthenameoftheAnttargetthatyouwanttorun.Ifyoudonotspecifyatarget,thevalueofthe@defaultattributefortheAntprojectisused.
Parenttopic:PublishingDITAcontentfromAnt
RelatedconceptsAnt
RelatedtasksCreatinganAntbuildscript
RelatedreferenceAntparametersApacheAntdocumentation
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.
<?xmlversion="1.0"encoding="UTF-8"?>
<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.
Parenttopic:PublishingDITAcontentfromAnt
RelatedconceptsAnt
RelatedtasksBuildingoutputusingAnt
RelatedreferenceAntparametersApacheAntdocumentation
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.
Parenttopic:PublishingDITAcontent
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
RelatedreferenceCommand-linetoolparameters
Buildingoutputusingthecommand-linetoolIfyouareunfamiliarwithAnt,youcaninvoketheDITAOpenToolkit(DITA-OT)andbuildoutputfromthecommand-linetool.
Procedure
1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.
2. Fromthecommandprompt,issuethefollowingcommand:
java-jarlib/dost.jar/i:input-file/transtype:transformation-type
where:
input-fileistheDITAmaporDITAfilethatyouwanttoprocess.
transformation-typeisthetransformationtype.
parameter-nameisthenameofanoptionalparameter.
valueisanapplicablevaluefortheoptionalparameter.
Ifyoudonotspecifyanoutputdirectory,bydefault,theDITA-OTwritestheoutputtotheinstallation-directory\outdirectory.
Example
ThefollowingcommandgeneratesHTML5outputforthesequence.ditamapfileandspecifiestheoutputiswrittentothetestdirectory
java-jarlib/dost.jar/i:samples/sequence.ditamap/outdir:test/transtype:html5
Parenttopic:PublishingDITAcontentfromthecommand-linetool
RelatedconceptsCommand-linetool
RelatedreferenceCommand-linetoolparameters
ExtendingtheDITAOpenToolkitPlug-inscanbeusedtoextendthefunctionalityandconfiguretheDITAOpenToolkit.
Installingplug-insPlug-insaredistributedaszipfilesandcanbeinstalledusingeitherthecommandlinetoolorAnt.
Removingplug-insPlug-inscanbeinstalledbyrunninguninstallationprocess.
Parenttopic:DITAOpenToolkitUserGuide
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
Parenttopic:ExtendingtheDITAOpenToolkit
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.
Parenttopic:DITAOpenToolkitUserGuide
RelatedreferenceLocalizationoverviewintheOASISDITAstandard
GlobalizationsupportofferedbytheDITA-OTTheDITAOpenToolkit(DITA-OT)offersglobalizationsupportinthefollowingareas:Generatedtext,indexsorting,andbi-directionaltext.
Generatedtext
GeneratedtextistextthatisrenderedautomaticallyintheoutputthatisgeneratedbytheDITA-OT;thistextisnotlocatedintheDITAsourcefiles.Thefollowingareexamplesofgeneratedtext:
Theword"ChapterinaPDFfile.
Thephrases"Relatedconcepts,""Relatedtasks,"and"Relatedreference"inXHTMLoutput.
Indexsorting
TheDITA-OTcanuseonlyasinglelanguagetosortindexes.
Bi-directionaltext
TheDITA-OTcontainsstylesheets(CSSfiles)thatsupportbothleft-to-right(LTR)andright-to-left(RTL)languages.
WhentheDITA-OTgeneratesoutput,ittakesthefirstvalueforthe@xml:langattributethatitencounters,andthenitusesthatvaluetocreategeneratedtext,performindexsorting,anddeterminewhichdefaultCSSfileisused.Ifnovalueforthe@xml:langattributeisfound,thetoolkitdefaultstoUSEnglish.
Parenttopic:GlobalizingDITAcontent
Supportedlanguages:HTML-basedtransformationsTheDITAOpenToolkit(DITA-OT)supportsover50languagesandlanguagevariantsfortheHTML-basedtransformations,forexample,EclipseHelp,HTMLHelp,andTocJS.
Table1.Supportedlanguages:HTML-basedtransformations
Language LanguagecodeArabic arorar-egBelarusian beorbe-byBrazilianPortuguese pt-brBulgarian bgorbg-bgCatalan ca-esChinese(simplified) zh-cnorzh-hansChinese(traditional) zh-tworzh-hantCroatian hrorhr-hrCzech csorcs-czDanish daorda-dkDutch nlornl-nlDutch(Belgian) nl-beEnglish(US) enoren-usEnglish(British) en-gbEnglish(Canadian) en-caEstonian etoret-eeFinnish fiorfi-fiFrench frorfr-frFrench(Belgian) fr-beFrench(Canadian) fr-caFrench(Swiss) fr-chGerman deorde-deGerman(Swiss) de-chGreek elorel-grHebrew heorhe-il
Hindi hiorhi-hiHungarian huorhu-huIcelandic isoris-isIndonesian idorid-idItalian itorit-itItalian(Swiss) it-chJapanese jaorja-jpKazakh kkorkk-kzKorean koorko-krLatvian lvorlv-lvLithuanian ltorlt-ltMacedonian mkormk-mkMalay msorms-myNorwegian noorno-noPolish plorpl-plPortuguese ptorpt-ptRomanian roorro-roRussian ruorru-ruSerbian(Cyrillicscript) sr,sr-rs,orsr-spSerbian(Latinscript) sr-latn-rsSlovak skorsk-skSlovenian slorsl-siSpanish esores-esSpanish(LatinAmerican) es-419Swedish svorsv-seThai thorth-thTurkish trortr-trUkrainian ukoruk-uaUrdu urorur-pk
Parenttopic:GlobalizingDITAcontent
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
Parenttopic:GlobalizingDITAcontent
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.
Parenttopic:DITAOpenToolkitUserGuide
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.
Seeparametersparametersandvalues.
DOTJ003F Fatal
Parameter'%1'wasspecifiedwithoutavalue.Parameterstothecommandlinetoolshouldusethesyntax/parameter:value.
Seeparametersparametersandvalues.
Thetransformwasunabletocreateatemporaryprocessingdirectory;thisisusuallycausedbyaccountcontrolsettingsthatpreventcreatingatemporarydirectoryinthespecified
DOTJ004F FatalCannotcreatetemporaryprocessingdirectory'%1'.Pleaseensurethatyouhavepermissiontocreatethedirectory'%1'.
location.Pleaseverifythatyouhavepermissiontowritetothedefaultlocation,orspecifyanalternatetemporarydirectorylocation.SeeargumentsCommandlinetoolargumentsfordetailsonhowtospecifythetemporarydirectory.
DOTJ005F FatalFailedtocreatenewinstancefor'%1'.Pleaseensurethat'%1'existsandthatyouhavepermissiontoaccessit.
DOTJ006F Fatal
AnAntbuildfileusedthefollowingillegalsyntaxwhencallingAntInvoker:extparam='%1'.PleasecorrectthecalltoAntInvokerwhendirectlycallingDITA-OTJavacodefromAnt;forexample,extparam="maplinks=XXXX;other=YYYY".
ThismessageoccurswhenanAntbuildcallsaDITA-OTpipelinemoduledirectlyinsteadofusingthedefaultcalltothatmodule.PleasecheckthatallparametersaresetcorrectlyinyourAntbuild.Thesyntaxforextparamis"name1=value1;name2=value2".
DOTJ007E ErrorDuplicateconditioninfilterfileforrule'%1'.Thefirstencounteredconditionwillbeused.
Ifaconditionisdefinedmorethanonce(suchassettingaudience="all"toinclude,thenresettingittoexclude),onlythefirstdefinitionwillbeused.
DOTJ009E Error
Cannotoverwritefile'%1'withfile'%2'.Themodifiedresultmaynotbeconsumedbythefollowingstepsinthetransformpipeline.Checktoseewhetherthefileislockedbysomeotherapplicationduringthetransformationprocess.
Thetransformwasunabletocreatefilesproperlyduringthetransform;resultsmaynotbeasexpected.
Thismessagemayindicateaninvalidinputfile(suchasaccidentallyspecifyingaPDFfileasinputratherthanaDITAmapfile),aninputfilethatuses
DOTJ012F Fatal Failedtoparsetheinputfile'%1'.TheXMLparserreportedthefollowingerror:
elementswhicharenotallowed,arenotpartoraDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.
DOTJ013E ErrorFailedtoparsethereferencedfile'%1'.TheXMLparserreportedthefollowingerror:
Thismessagemayindicateareferencetoaninvalidfile(suchasaccidentallyreferencingaPDForunknownXMLfileasifitwasDITA),areferencedfilethatuseselementswhicharenotallowed,orareferencedDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.
DOTJ014W Warning Foundanindextermelementwithnocontent.Settingthetermto***.
Anempty<indexterm>elementwasfound,andwillappearintheindexas***.Thisindextermshouldberemovedfromthesource.
DOTJ015F Fatal Logdirectorycannotbenull.Pleasespecifyavaliddirectoryforthebuildlog.
DOTJ016F Fatal Failedtocreatelogdirectory'%1'.Pleasespecifyavaliddirectoryforthebuildlog.
DOTJ017F Fatal Noinputfilewasspecified;failedtoinitializelognamebasedoninputfile.
Thetransformfailedbecausetheinputfilewasnotspecified;logfilenamesarebasedonthenameoftheinputfile,sonologcouldbegenerated.
DOTJ018I Informational
Logfile'%1'wasgeneratedsuccessfullyindirectory'%2'.Anymessagesfromthetransformationprocessareavailableinthelogfile;additionaldetailsabouteachmessageareavailableintheDITA-OTuserguide.
DOTJ020W Warning
Atleastoneplug-inin'%1'isrequiredbyplug-in'%2'.Plug-in'%2'cannotbeloaded.Checkandseewhetherallprerequisiteplug-insareinstalledintoolkit.
Thiswillappearwhenoneinstalledplug-inrequiresanotherinordertofunctioncorrectly,buttherequiredplug-inisnotfound.Theinstalledplug-inwillbeignored.
DOTJ021W Warning
File'%1'willnotgenerateoutputsinceitisinvalidorallofitscontenthasbeenfilteredoutbytheditavalfile.Pleasecheckthefile'%1'andtheditavalfiletoseeifthisistheintendedresult.
Thismayappeariffilterconditionsontherootelementofatopiccausetheentiretopictobefilteredout.Toremovethismessage,youcouldplaceanyfilterconditionsonthereferencetothisfile,whichwillpreventthebuildfromaccessingthisfile.
DOTJ022F Fatal
Failedtoparsetheinputfile'%1'becauseallofitscontenthasbeenfilteredout.Thiswillhappeniftheinputfilehasfilterconditionsontherootelement,andaditavalexcludesallcontentbasedonthoseconditions.
Eithertheinputfileortheditavalfileshouldchange,otherwiseyourbuildisexplicitlyexcludingallcontent.
DOTJ023E Error Failedtogetthespecifiedimagefile'%1',soitwillnotbeincludedwithyouroutput.
Checkwhethertheimageexistsinthesourcelocationoralreadyexistsintheoutputdirectory.Thismessageshouldonlyappearinthefollowingcases:
DOTJ025E Error
Theinputtothe"topicmerge"transformprocesscouldnotbefound.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.
DOTJ026E Error
The"topicmerge"didnotgenerateanyoutput.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.
ThismessageshouldonlyappearifanAntbuildorplug-inisdirectlycallingthetoolkit'stopicmergemodule,orifearliererrorsresultedinproblemswithsomeofthecontent.Ifthetopicmergemoduleiscalledcorrectly,thenthisindicatesaprogramerrorthatshouldbereportedtotheDITA-OTdevelopmentteam,atbugandfeaturetracker
DOTJ028E Error
Noformatattributewasfoundonareferencetofile'%1',whichdoesnotappeartobeaDITAfile.Ifthisisnota
Whenreferencinganon-DITAfile,theformatattributeshouldindicatethetypeoffilereferenced(suchas"html"forHTMLtopicsor"pdf"forPDF
DITAfile,settheformatattributetoanappropriatevalue,otherwisesettheformatattributeto"dita".
files).Otherwise,thetransformmayattempttoparsethereferenceddocumentasaDITAtopic.
DOTJ029I Informational
No'domains'attributewasfoundforelement'<%1>'.ThisgenerallyindicatesthatyourDTDorSchemawasnotdevelopedproperlyaccordingtotheDITAspecification.
ThedomainsattributeisusedinspecializedDITAdocumentstohelpdeterminewhichdomainelementsarelegal.ThismessagewillonlyappearifDITAspecializationwasnotdefinedproperly.
DOTJ030I Informational
No'class'attributeforwasfoundforelement'<%1>'.ThisgenerallyindicatesthatyourDTDorSchemawasnotdevelopedproperlyaccordingtotheDITAspecification.
AllspecializedDITAelementsmustdefineaclassattributetoprovideancestryinformation.ThismessagewillonlyappearaspecializedDITAelementdidnotdefineaclassattribute.
DOTJ031I Informational
Nospecifiedrulefor'%1'wasfoundintheditavalfile.Thisvaluewillusethedefaultaction,oraparentpropactionifspecified.Toremovethismessage,youcanspecifyarulefor'%1'intheditavalfile.
Thisinformationalmessageisintendedtohelpyoucatchfilterconditionsthatmayhavebeenspecifiedimproperly;ifthevalueiscorrect,noactionisneeded.
DOTJ033E ErrorNovalidcontentisfoundintopicref'%1'duringchunkprocessing.Pleasespecifyanexistingandvalidtopicforthetopicref.
DOTJ034F Fatal
Failedtoparsetheinputfile'%1'(thecontentofthefileisnotvalid).Iftheinputfile'%1'doesnothaveaDOCTYPEdeclaration,pleasemakesurethatallclassattributesarepresentinthefile.
DITAprocessingisbasedonclassattributesdefinedforeveryelement.UsuallythesearedefaultedintheDTDorSchema;ifnoDTDorSchemaisused,theclassattributesmustbeexplicitlyincludedinthemaportopic.
Thefile"%1"referencedby"%2"is
Thisoutsidethescopeofthemap;forexample,ifthemaininputmapreferences
DOTJ035F Fatal
outsidethescopeoftheinputdita/mapdirectory.Ifyouwanttolowertheseveritylevel,pleaseusetheAntparameter'outer.control',andsetthevalueto"warn"or"quiet".Otherwise,movethereferencedfile"%1"intotheinputdita/mapdirectory.
directory/some.dita"
resultwouldcauseanoutputfiletobecreatedoutsideoftheoutputdirectory.PleaseseeDITA-OTAntarguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)
DOTJ036W Warning
Thefile"%1"referencedby"%2"isoutsidethescopeoftheinputdita/mapdirectory.Ifyoudonotwanttoseethewarningmessage,pleaseusetheAntparameter'outer.control',andsetthevalueto"quiet".Otherwise,movethereferencedfile"%1"intotheinputdita/mapdirectory.
Thisoutsidethescopeofthemap;forexample,ifthemaininputmapreferencesdirectory/some.dita"
resultwouldcauseanoutputfiletobecreatedoutsideoftheoutputdirectory.DITA-OTAntarguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)
DOTJ037W Warning
TheXMLschemaandDTDvalidationfunctionoftheparseristurnedoff.PleasemakesuretheinputisnormalizedDITAwithclassattributesincluded,otherwiseitwillnotbeprocessedcorrectly.
DITAprocessingisbasedonclassattributesdefinedforeveryelement.UsuallythesearedefaultedintheDTDorSchema;ifvalidationagainsttheDTDorSchemaisturnedoff,theclassattributesmustbeexplicitlyincludedinthemaportopic.
DOTJ038E Error
Thetag"%1"isspecializedfromunrecognizedmetadata.Pleasemakesurethattag"%1"isspecializedfromanexistingmetadatataginthecoreDITAvocabulary.
Thisappearstoindicateanerrorincreatingspecializedmetadataelements.Pleaseverifythatthedocumenttypeyouareusingiscompleteandcomplieswith
DITASpecializationrules.
DOTJ039E Error
Thereisnotargetspecifiedforconrefpushaction"pushafter".Foundinfile="%1",element="%2".Pleaseadd<elementnameconref="pushtarget"conaction="mark">beforecurrentelement.
PleaseseethetopiconPushfordetailsonexpectedsyntaxforthisfunction.
DOTJ040E Error
Anelementusestheattributeconaction="replace",butaconrefattributeisnotfoundintheexpectedlocation.Foundinfile="%1",element="%2".
PleaseseethetopiconPushfordetailsonexpectedsyntaxforthisfunction.
DOTJ041E Error
Theattributeconref="%1"usesinvalidsyntax.Thevalueshouldcontain'#'followedbyatopicormapID,optionallyfollowedby'/elemID'forasub-topicelement.
TheconrefattributemustbeaURIreferencetoaDITAelement.PleaseseethetopiconURI-basedaddressingDITAspecificationfordetailsontheexpectedsyntax.
DOTJ042E ErrorTwoelementsbothuseconrefpushtoreplacethetarget"%1".Pleasedeleteoneoftheduplicate"replace"actions.
Theconrefpushfunctionwasusedtoreplaceasingleelementwithtwoormorealternatives.Onlyoneelementmaydirectlyreplaceanotherusingconrefpush.SeeDITAspecificationformoreinformationabouttheconrefpush"replace"function.
DOTJ043W WarningTheconrefpushfunctionistryingtoreplaceanelementthatdoesnotexist(element"%1"infile"%2").
Thetargetforaconrefpushactiondoesnotexist;pleasemakesurethatthesyntaxiscorrectandthatthetargetexists.Seethetopiconbasedaddressingspecificationfordetailsontheexpectedsyntax.Ifthesyntaxiscorrect,itispossiblethatthetargetwasfilteredoutofyourbuildusingaDITAVALfile.
Thereisaredundantconrefaction Pleaseseethetopicon
DOTJ044W Warning "pushbefore".Foundinfile="%1",element="%2".Pleasemakesurethat"mark"and"pushbefore"occurinpairs.
Pushfordetailsonexpectedsyntaxforthisfunction.
DOTJ045I InformationalThekey"%1"isdefinedmorethanonceinthesamemapfile.Thereferencehref="%2"isignored.
Noresponseisneededifthekeysaredefinedasexpected;thisisinformationalonly,tohelpcatchincorrectlydefinedkeys.
DOTJ046E Error
Conkeyref="%1"cannotberesolvedbecauseitdoesnotcontainakeyorthekeyisnotdefined.Thebuildwillusetheconrefattributeforfallback,ifoneexists.
Seedetailsonexpectedsyntaxandusage.
DOTJ047I InformationalUnabletofindkeydefinitionforkeyref="%1",hrefmaybeusedasfallbackifitexists.
Thismessageisintendedtohelpyoulocateincorrectlyspecifiedkeys;ifthekeywasspecifiedcorrectly,thismessagemaybeignored.
DOTJ049W Warning
Theattributevalue%1="%3"onelement"%2"doesnotcomplywiththespecifiedsubjectscheme.Accordingtothesubjectschememap,thefollowingvaluesarevalidforthe%1attribute:%4
ADITAwasusedtolimitvaluesthatareavailabletothespecifiedattribute.Pleasecorrecttheattributesothatitusesoneoftheallowedvalues.
DOTJ050W WarningFoundan<index-see>or<index-see-also>referencetotheterm'%1',butthattermisnotdefinedintheindex.
TheEclipseindexwillcontainavaluesuchas"SeealsootherEntry",butotherEntrydoesnotexistinthisindex.Theindexreferencewillbebrokenunlessthisplug-inisEclipsewithanotherplug-inthatdefinesotherEntryasanindexterm.Thetargetforacoderefelement,whichspecifiesanexternaltext-basedfile,couldnotbelocatedorloaded.Pleaseverifythatthereferenceiscorrect.
DOTJ051E Error Unabletoloadtargetforcoderef"%1".
Notethatforsecurityreasons,referencestocodesamplesoutsideofthescopeofthemapdirectoryarenotsupportedbydefault,asthiscouldallowareferencetoaccessanddisplayanyrestrictedorhiddenfileonthesystem.Ifyouarecertainthatthepathisvalidandthefileshouldbeloaded,thecurrentworkaroundistosetaparametertoallowthesereferences.Seearguments(outer.controlandgenerate.copy.outer)OTCommandlinetoolarguments(/outercontroland/generateouter)
DOTJ052E Error
Codereferencecharset"%1"notsupported.SeetheDITA-OTUserguideforsupportedcharsetvaluesontheformatattribute.
TheDITA-OTsupportsaspecialsyntaxoncoderefelementstospecifythecharactersetofthetargetdocument.Seefunctionalityexpectedsyntax.
DOTJ053W Warning
Inputfile'%1'isnotvalidDITAfilename.Pleasecheck'%1'toseeifitiscorrect.Theextensions".dita"or".xml"aresupportedforDITAtopics.
Bydefault,theDITA-OTsupportstheextensions"dita"and"xml"forDITAtopics,asmandatedbytheDITASpecification.Pleaseverifythatyourtopicsuseoneoftheseextensions,orconfigurethetoolkittoallowadditionalextensions.
DOTJ054E Error Unabletoparseinvalid%1attributevalue"%2"
DOTJ055E Error Invalidkeyname"%1".
DOTJ056E Error Invalidxml:lang"%1".
DOTJ057E Error Theidattributevalue"%1"isnotuniquewithinthetopicthatcontainsit.
DOTJ058E Error
Both%1and%2attributesdefined.Asingleelementmaynotcontainbothgeneralizedandspecializedvaluesforthesameattribute.
DOTJ059E Error Invalidkeyscopename"%1".
DOTJ060W Warning
Key"%1"wasusedinconkeyrefbutisnotboundtoaDITAtopicormap.Cannotresolveconkeyrefvalue"%2"asavalidconrefreference.
DOTX001WWarning
Nostringnamed'%1'wasfoundforlanguage'%2'.Usingthedefaultlanguage'%3'.Addamappingbetweendefaultlanguageanddesiredlanguageforthestring'%1'.
Thisbuildusesgeneratedtext,suchasthephrase"Relatedinformation"(whichisgeneratedabovemanylinkgroups).Thetoolkitwasunabletolocatethestringlanguage,sothestringwillappearinthedefaultlanguage.Thisgenerallyindicatesthatthetoolkit'sstringsneedstobeupdatedtosupportyourlanguage,orthatyourlanguagesettingisincorrect.
DOTX002WWarning ThetitleelementorattributeintheditamapisrequiredforEclipseoutput.
TheEclipsehelpsystemrequiresatitleintheprojectfilesgeneratedfromyourmap.PleaseaddatitletoyourinputmaptogetvalidEclipsehelpoutput.
DOTX003I Informational
TheanchorrefattributeshouldeitherreferenceanotherditamaporanEclipseXMLTOCfile.Thevalue'%1'doesnotappeartoreferenceeither.
EclipseusesanchorreferencestoconnectwithotherTOCfiles.ForthistoworkincontentgeneratedfromaDITAmap,theanchorrefelementmustreferenceeitheranexistingEclipseTOCXMLfile,or
anotherDITAmap(whichwillpresumablyalsobeconvertedtoanEclipseTOC).
DOTX004I Informational
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").
DOTX007I Informational
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.
DOTX018I Informational
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.
DOTX029I Informational
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.
DOTX038I Informational
Thelongdescrefattributeontag'%1'willbeignored.Accessibilityforobjectelementsneedstobehandledanotherway.
The<object>elementinXHTMLdoesnotsupportusinglongdescrefforaccessibility.Tomaketheobjectaccessible,youmayneedtoaddtextbeforeoraftertheelement.Youmayalsobeabletohandleitwitha<param>elementinsidetheobject.
DOTX039WWarning
Requiredcleanupareafound.Toremovethismessageandhidethecontent,buildyourcontentwithoutusingtheDRAFTparameter.
Thismessageisgeneratedwhencreatingdraftoutputinordertohelpyoulocatealltopicsthatneedtobecleanedup;thecleanupitemswillappearinyouroutputwithstylingthatmakesitstandout.
Thecontentwillbehiddenwhenthedraftparameterisnotactive.
DOTX040I Informational
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.
DOTX048I Informational
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
DOTX062I Informational
Itappearsthatthisdocumentusesconstraints,buttheconrefprocessorcannotvalidatethatthetargetofaconrefisvalid.Toenableconstraintchecking,pleaseupgradetoanXSLT2.0processor.
DOTX063WWarning
Theditadocument'%1'islinkedtofromyourcontent,butisnotreferencedbyatopicreftagintheditamapfile.Includethetopicinyourmaptoavoidabrokenlink.
ThiswillappearwhengeneratingPDForODToutputthatincludesalinktoalocaltopic,butthereferencedtopicisnotpartofthemapitself.Thiswillresultinabrokenlink.Youshouldincludethetopicinyourmaporremovethelinkfromthebuild.
DOTX064WWarningThecopy-toattribute[copy-to="%1"]usesthenameofafilethatalreadyexists,sothisattributeisignored.
Thecopy-toattributeisusedtocopyatopicoveradocumentthatalreadyexists.Pleasemakesurethatanycopy-toattributesuseauniquenamesothatthecopywillnotoverwriteexistingcontent.
DOTX065WWarning
Twouniquesourcefileseachspecifycopy-to="%2",whichresultsinacollision.Thevalueassociatedwithhref="%1"isignored.
Twodifferenttopicsarecopiedtothesamelocationusingcopy-to;asaresult,oneofthesefileswouldbeover-written.Onlythefirstinstanceofthiscopy-tovaluewillberecognized.Pleasecorrecttheuseofcopy-toattributes.
Template"%1"isdeprecated.Remove
ThismessageindicatesthatyourcustomXSLTorplug-insrelyontemplatesthatwillberemovedinanupcoming
DOTX066WWarning referencestothistemplatefromyourcustomXSLTorplug-ins.
release.Typicallythisoccurswhenanamedtemplatehasbeenconvertedtoamodetemplate;anycodethatusesthedeprecatedtemplateshouldbeupdated.
DOTX067E ErrorNostringnamed'%1'wasfoundforlanguage'%2'.Addamappingforthestring'%1'.
ThisPDFbuildusesgeneratedtext,suchasthephrase"Relatedinformation"(whichisgeneratedabovemanylinkgroups).Thetoolkitwasunabletolocatethestringspecifiedlanguage,sothestringwillappearinthedefaultlanguage.Thisgenerallyindicatesthatthetoolkit'sstringsneedstobeupdatedtosupportyourlanguage,orthatyourlanguagesettingisincorrect.
DOTX068WWarningAtopicrefelementthatreferencesamapcontainschildtopicrefelements.Childtopicrefelementsareignored.
PDFJ001E Error Indexentry'%1'isdropped,becausecorrespondinggroupisnotfound.
PDFJ002E ErrorBuildstopped.ProblemsoccuredduringIndexpreprocesstask.Pleasecheckthemessagesabove.
PDFX001W Warning ThereisnoindexentryfoundwhichclosingrangeforID="%1".
PDFX002W Warning
TherearemultipleindexentryfoundwhichisopeningrangeforID="%1"butthereisonlyonewhichcloseitorrangesareoverlapping.
PDFX003W Warning TherearemultipleindexentryfoundwhichclosingrangeforID="%1".
PDFX004F FatalEmptyhrefwasspecifiedforsometopicreference.Pleasecorrectyourditamaporbookmapfile.
PDFX005F FatalTopicreference(href:%1)notfound.Referencemaybeincorrect.Pleasecorrectyourditamaporbookmapfile.
PDFX006E Error Numberofcolumnsmustbespecified.
PDFX007W Warning ThereisnoindexentryfoundwhichopeningrangeforID="%1".
PDFX008W Warning Fontdefinitionnotfoundforthelogicalnameoralias'%1'.
PDFX009E Error Attributesetreflectioncan'thandleXSLTelement%1.
PDFX010W Warning IndexgenerationisnotsupportedinFOP.
PDFX011E ErrorBothindex-seeand%1definedforindexentry'%2'.Recoveringbytreatingtheindex-seeasanindex-see-also.
PDFX012F FatalUnrecognizedPDFformatter'%1'.Use"fop"forFOP,"xep"forRenderXXEP,or"ah"forAHFormatter.
XEPJ001W Warning %1 XEPJ002E Error %1 XEPJ003E Error %1
Parenttopic:Errormessagesandtroubleshooting
OthererrormessagesInadditiontoerrormessagesgeneratedbytheDITAOpenToolkit,youmightalsoencountererrormessagesgeneratedbyJavaorothertools.
OutofMemoryerror
Insomecases,youmightreceiveamessagestatingthebuildhasfailedduetoanOutofMemoryerror.Trythefollowingapproachestoresolvetheproblem:
1. IncreasethememoryavailabletoJava;seeIncreasingJavamemoryallocation.
2. Reducememoryconsumptionbysettingthegenerate-debug-attributesoptiontofalse.Thisoptionissetinthelib/configuration.propertiesfile.Thiswilldisabledebugattributegeneration(usedtotraceDITA-OTerrormessagesbacktosourcefiles)andwillreducememoryconsumption.
3. Setdita.preprocess.reloadstylesheetAntpropertytotrue.ThiswillallowtheXSLTprocessortoreleasememorywhenconvertingmultiplefiles.
4. Runthetransformationagain.
java.io.IOException:Can'tstoreDocument
AfterrunningaJavaHelptransformation,youmayreceiveajava.io.IOException:Can'tstoreDocumentmessage.
ThisproblemoccurswhenHTMLfilesunrelatedtothecurrenttransformationarefoundintheoutputdirectory.Deletethecontentoftheoutputdirectoryandrunthetransformationagain.
StackOverflowerror
Ifyoureceiveanerroraboutastackmemoryoverflow,increasetheJVMandrunthetransformationagain.SeeIncreasingJavamemoryallocation.
Parenttopic:Errormessagesandtroubleshooting
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.
Parenttopic:Errormessagesandtroubleshooting
Accessinghelpfromthecommand-linetoolYoucanaccessalistofsupportedparametersforthecommand-linetoolbyissuingthe-helpparameter.
Procedure
1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.
2. Fromthecommandprompt,issuethefollowingcommand:
java-jarlib/dost.jar-help
Results
Youcanseethebriefdescriptionofthesupportedparametersinthecommand-linewindow.
Parenttopic:Errormessagesandtroubleshooting
DetermingtheversionoftheDITAOpenToolkitYoucanusethecommand-linetooltodeterminetheversionoftheDITAOT.
Procedure
1. Runthestartcmdfilethatisapplicableforyouroperatingsystem.Thestartcmd.batandstartcmd.shfilesareinthedirectorywhereyouinstalledtheDITA-OT.
2. Fromthecommandprompt,issuethefollowingcommand:
java-jarlib/dost.jar-version
Parenttopic:Errormessagesandtroubleshooting
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"/>
Parenttopic:Errormessagesandtroubleshooting
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.
Parenttopic:Errormessagesandtroubleshooting
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.
Parenttopic:DITAOpenToolkitUserGuide
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
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.
Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.
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.
Parenttopic:Antparameters
RelatedreferenceAntparameters:EclipsecontenttransformationAntparameters:EclipsehelptransformationAntparameters:HTMLHelptransformationAntparameters:JavaHelptransformationAntparameters:HTML5andXHTMLtransformation
Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.
Figure1.Antparameters:Eclipsecontenttransformation
args.eclipsecontent.toc
SpecifiesthenameoftheTOCfile
Parenttopic:Antparameters
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.
Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.
args.eclipse.symbolic.name
Specifiesthesymbolicname(akapluginID)intheoutputforanEclipseHelpproject.The@idvaluefromtheDITAmaportheEclipsemapcollection(Eclipsehelpspecialization)isthesymbolicnamefortheplugininEclipse.Thedefaultvalueisorg.sample.help.doc.
Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.
Parenttopic:Antparameters
RelatedconceptsEclipsehelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.
Figure1.Antparameters:HTMLHelptransformation
args.htmlhelp.includefile
SpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.
Parenttopic:Antparameters
RelatedconceptsHTMLhelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.
Figure1.Antparameters:JavaHelptransformation
args.javahelp.map
SpecifiesthenameoftheditamapfileforaJavaHelpproject.
args.javahelp.toc
SpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.
Parenttopic:Antparameters
RelatedconceptsJavaHelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.
Figure1.Antparameters:ODTtransformation
args.odt.img.embed
DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.
Parenttopic:Antparameters
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.
Parenttopic:Antparameters
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.
Parenttopic:Antparameters
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.
Parenttopic:Antparameters
RelatedconceptsXHTMLtransformationHTML5transformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
ditacommandargumentsandoptionsTheditacommandtakesmandatoryargumentstoprocessDITA,manageplug-in,orprintinformationaboutthecommand.Optionscanbeusedmodifythecommandbehaviourorprovideadditionalconfiguration.
Usage
dita-fname-ifile[options]
dita-install{file|url}
dita-uninstallid
dita-help
dita-version
Arguments
-f,-formatname
Specifiestheoutputformat.Youcancreateplug-instoaddnewvaluesforthisparameter;bydefault,thefollowingvaluesareavailable:
docbook
eclipsehelp
eclipsecontent
html5
htmlhelp
javahelp
odt
wordrtf
troff
xhtml
-i,-inputfile
Specifiesthemasterfileforyourdocumentationproject.TypicallythisisaDITAmap,howeveritalsocanbeaDITAtopicifyouwanttotransformasingleDITAfile.Thepathcanbeabsolute,relativetoargs.input.dir,orrelativetothedirectorywhereyourproject'santbuildscriptresidesifargs.input.dirisnotdefined.
-installfile-installurl
Installplug-infromalocalZIPfileorfromaURL.
-uninstallid
Uninstallplug-inwiththeID.
-h,-help
Printcommandusagehelp.
-version
Printversioninformationandexit.
Options
-o,-outputdir
Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentooutsubdirectoryofthecurrentdirectory.
-filterfile
Specifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.
-tempdir
Specifiesthelocationofthetemporarydirectory.ThetemporarydirectoryiswheretheDITA-OTwritestemporaryfilesthataregeneratedduringthetransformationprocess.
-v,-verbose
Verboselogging.
-d,-debug
Debuglogging.
-l,-logfilefile
Outputloggingmessagesintoafile.
-Dproperty=value
Specifyavalueforaproperty.SupportedpropertiesarethesameasAntparametersandaretransformationtypespecific.
-propertyfilefile
Loadallpropertiesfromafile.Propertiesspecifiedwith-Doptiontakeprecedence.
Parenttopic:Reference
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.
Parenttopic:Reference
RelatedconceptsCommand-linetool
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
Specifiesthemasterfileforyourdocumentationproject.TypicallythisisaDITAmap,howeveritalsocanbeaDITAtopicifyouwanttotransformasingleDITAfile.Thepathcanbeabsolute,relativetoargs.input.dir,orrelativetothedirectorywhereyourproject'santbuildscriptresidesifargs.input.dirisnotdefined.
logdir
SpecifiesthelocationwheretheDITA-OTplaceslogfilesforyourproject.
outdir
Specifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.
tempdir
Specifiesthelocationofthetemporarydirectory.ThetemporarydirectoryiswheretheDITA-OTwritestemporaryfilesthataregeneratedduringthetransformationprocess.
transtype
Specifiestheoutputformat.Youcancreateplug-instoaddnewvaluesforthisparameter;bydefault,thefollowingvaluesareavailable:
docbook
eclipsehelp
eclipsecontent
html5
htmlhelp
javahelp
odt
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.
Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.
generateouter
SpecifieswhethertogenerateoutputfilesforcontentthatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:
1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory.
3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.
Seegenerate.outer.copyparameterformoreinformation.
hdf
SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.
hdr
SpecifiesanXMLfilethatcontainscontentforarunningheader.CorrespondstotheXSLTparameterHDR.
Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.
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.
Parenttopic:Command-linetoolparameters
RelatedreferenceCommand-linetoolparameters:EclipsecontenttransformationCommand-linetoolparameters:EclipsehelptransformationCommand-linetoolparameters:HTMLhelptransformationCommand-linetoolparameters:JavaHelptransformationCommand-linetoolparameters:HTML5andXHTMLtransformation
Command-linetoolparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.
Figure1.Command-linetoolparameters:Eclipsecontenttransformation
eclipsecontenttoc
SpecifiesthenameoftheTOCfile
Parenttopic:Command-linetoolparameters
RelatedconceptsEclipsecontenttransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.
Figure1.Command-linetoolparameters:Eclipsehelptransformation
eclipsehelptoc
SpecifiesthenameoftheTOCfile.
provider
SpecifiesthenameofthepersonororganizationthatprovidestheEclipsehelp.ThedefaultvalueisDITA.
Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.
version
Specifiestheversionnumbertoincludeintheoutput.Thedefaultvalueis0.0.0.
Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.
Parenttopic:Command-linetoolparameters
RelatedconceptsEclipsehelptransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:HTMLhelptransformationCertainparametersarespecifictotheHTMLhelptransformation.
Figure1.Command-linetoolparameters:HTMLhelptransformation
htmlhelpincludefile
SpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.
Parenttopic:Command-linetoolparameters
RelatedconceptsHTMLhelptransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.
Figure1.Command-linetoolparameters:JavaHelptransformation
javahelpmap
SpecifiesthenameoftheditamapfileforaJavaHelpproject.
javahelptoc
SpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.
Parenttopic:Command-linetoolparameters
RelatedconceptsJavaHelptransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.
Figure1.Command-linetoolparameters:ODTtransformation
odtimgembed
DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.
Parenttopic:Command-linetoolparameters
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.
Parenttopic:Command-linetoolparameters
RelatedconceptsPDFtransformation
RelatedreferenceCommand-linetoolparameters:Alltransformations
Command-linetoolparameters:HTML5andXHTMLtransformationCertainparametersarespecifictotheHTML5andXHTMLtransformation.
Figure1.Command-linetoolparameters:HTML5andXHTMLtransformation
xhtmltoc
SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.
Parenttopic:Command-linetoolparameters
RelatedconceptsXHTMLtransformationHTML5transformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
lib/configuration.propertiesfileThelib/configuration.propertiesfilecontrolscertaincommonproperties,aswellassomepropertiesthatcontrolPDFprocessing.
Table1.Propertiessetinthelib/configuration.propertiesfileProperty Description
default.language
Specifiesthelanguagethatisusediftheinputfiledoesnothavethe@xml:langattributesetontherootelement.Bydefault,thisissettoen.TheallowedvaluesarethosethataredefinedinIETFBCP47,TagsfortheIdentificationofLanguages.
generate-debug-attributes
Specifieswhetherthe@xtrfand@xtrcdebuggingattributesaregeneratedinthetemporaryfiles.Thefollowingvaluesareallowed:
true(default)—Enablesgenerationofdebuggingattributes
false—Disablesgenerationofdebuggingattributes
Note:Disablingdebuggingattributesreducesthesizeoftemporaryfilesandthusreducesmemoryconsumption.However,thelogmessagesnolongerhavethesourceinformationavailableandthustheabilitytodebugproblemsmightdeteriorate.
SpecifieshowtheDITA-OThandleserrorsanderrorrecovery.Thefollowingvaluesareallowed:
strict—Whenanerrorisencountered,theDITA-OTstopsprocessing.
processing-mode lax(default)—Whenanerrorisencountered,theDITA-OTattemptstorecoverfromit.
skip—Whenanerrorisencountered,theDITAcontinuesprocessingbutdoesnotattempterrorrecovery.
org.dita.pdf2.i18n.enabled
(PDFtransformationonly)EnablesI18Nfontprocessing.Thefollowingvaluesareallowed:
true(default)—EnablesI18Nprocessing
false—DisablesI18Nprocessing
org.dita.pdf2.use-out-temp
(PDFtransformationonly)SpecifieswhethertheXSL-FOprocessingwritestheintermediatefiles(forexample,thetopic.fofile)totheoutputdirectory.Thefollowingvaluesareallowed:
true—Writeintermediatefilestotheoutputdirectory
false(default)—Writeintermediatefilestothetemporarydirectory
plugindirs
Asemicolon-separatedlistofdirectorypathsthattheDITA-OTsearchesforplug-instointegrate;anyrelativepathsareresolvedagainsttheDITA-OTbasedirectory.Anyimmediatesubdirectorythatcontainsaplugin.xmlfileisintegrated
plugin.ignoresAsemicolon-separatedlistofdirectorynamestobeignoredduringplug-inintegration;anyrelativepathsareresolvedagainsttheDITA-OTbasedirectory.
Parenttopic:Reference
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.
Parenttopic:ArchitectureoftheDITAOpenToolkit
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..
Parenttopic:ArchitectureoftheDITAOpenToolkit
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.
Parenttopic:ArchitectureoftheDITAOpenToolkit
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
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.
<?xmlversion="1.0"encoding="UTF-8"?>
<val>
<!--Definewhathappensinthecaseofconflictingstyles-->
<style-conflictbackground-conflict-color="red"/>
<!--Definetwoflaggingpropertiesthatgivestyles(noimage)-->
<propaction="flag"att="audience"style="underline"val="user"backcolor="green"/>
<propaction="flag"att="platform"style="overline"val="win"backcolor="blue"/>
<!--Defineapropertythatincludesstartandendimageflags-->
<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>
<!--Definearevisionthatincludesstartandendimageflags-->
<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;">
<propaction="flag"att="audience"style="underline"val="user"backcolor="green"/>
</ditaval-startprop>
Simpleuser;includesstylebutnoimages
<ditaval-endpropclass="+topic/foreignditaot-d/ditaval-endprop">
<propaction="flag"att="audience"style="underline"val="user"backcolor="green"/>
</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.
Theresultingfileaftertheflaggingsteplookslikethis;forclarity,newlinesareadded,while@xtrfand@xtrcareremoved:
<paudience="user"platform="win"class="-topic/p">
<ditaval-startpropclass="+topic/foreignditaot-d/ditaval-startprop"
outputclass="background-color:red;">
<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"/>
</ditaval-startprop>
Conflictingstyles(stillnoimages)
<ditaval-endpropclass="+topic/foreignditaot-d/ditaval-endprop">
<propaction="flag"att="platform"style="overline"val="win"backcolor="blue"/>
<propaction="flag"att="audience"style="underline"val="user"backcolor="green"/>
</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>.
Theresultingfileaftertheflaggingsteplookslikethis;forclarity,newlinesareadded,while@xtrfand@xtrcareremoved:
<olplatform="linux"rev="rev2"class="-topic/ol">
<ditaval-startpropclass="+topic/foreignditaot-d/ditaval-startprop"
outputclass="background-color:blue;text-decoration:underline;text-decoration:overline;">
<propaction="flag"att="platform"val="linux"style="overline"backcolor="blue">
<startflagimageref="startlin.png"><alt-text>Startlinux</alt-text></startflag>
</prop>
<revpropaction="flag"style="double-underline"val="rev2">
<startflagimageref="start_rev.gif"><alt-text>ssssssssssstart</alt-text></startflag>
</revprop>
</ditaval-startprop>
<liclass="-topic/li">Generateimagesforplatform="linux"andrev="2"</li>
<ditaval-endpropclass="+topic/foreignditaot-d/ditaval-endprop">
<revpropaction="flag"style="double-underline"val="rev2">
<endflagimageref="end_rev.gif"><alt-text>eeeeeeeeeeeeeend</alt-text></endflag>
</revprop>
<propaction="flag"att="platform"val="linux"style="overline"backcolor="blue">
<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.
Parenttopic:ArchitectureoftheDITAOpenToolkit
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.
Parenttopic:HTML-basedprocessingmodules
HTML5processingAftertheHTML5filesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythehtml5transformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.
Parenttopic:HTML-basedprocessingmodules
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.
Parenttopic:HTML-basedprocessingmodules
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.
Parenttopic:HTML-basedprocessingmodules
HTMLHelpprocessingThehtmlhelptransformationcreatedHTMLHelpcontrolfiles.IfthebuildrunsonasystemthathastheHTMLHelpcompilerinstalled,thecontrolfilesarecompiledintoaCHMfile.
Oncethepre-processingandXHTMLprocessesarecompleted,mostoftheHTMLHelpprocessingishandledbythefollowingtargets:
dita.map.htmlhelp
CreatetheHHP,HHC,andHHKfiles.TheHHKfileissortedbasedonthelanguageofthemap.
dita.htmlhelp.convertlang
Ensuresthatthecontentcanbeprocessedcorrectlybythecompiler,andthattheappropriatecodepagesandlanguagesareused.
compile.HTML.Help
AttemptstodetecttheHTMLHelpcompiler.Ifthecompilerisfound,thefullprojectiscompiledintoasingleCHMfile.
Parenttopic:HTML-basedprocessingmodules
JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.
TherearetwoprimaryAnttargets:
dita.map.javahelp
CreatesallofthefilesthatareneededtocompileJavaHelp,includingatableofcontents,sortedindex,andhelpmapfile.
compile.Java.Help
SearchesforaJavaHelpcompileronthesystem.Ifacompilerisfound,thehelpprojectiscompiled.
Parenttopic:HTML-basedprocessingmodules
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.
Parenttopic:ArchitectureoftheDITAOpenToolkit
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.
Parenttopic:ArchitectureoftheDITAOpenToolkit
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.
Parenttopic:DITAOpenToolkitDeveloperReference
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
Parenttopic:ExtendingtheDITAOpenToolkit
Manuallyremovingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.
Procedure
1. Removeplug-ininstallationdirectory.
2. Runintegrationprocess.
ant-fintegrator.xml
Parenttopic:ExtendingtheDITAOpenToolkit
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.
Parenttopic:ExtendingtheDITAOpenToolkit
ConfiguringtheDITAOpenToolkitTheDITAOTuses.propertiesfilesthatstoreconfigurationsettingsfortheDITAOTanditsplug-ins.TheconfigurationpropertiesareavailabletobothAntandJavaprocesses,butunlikeargumentproperties,theycannotbesetatruntime.
plugin.propertiesfileTheplugin.propertiesfileisusedtostoreconfigurationpropertiesthataresetbytheintegrationprocess.Thefileislocatedinthelib\org.dita.dost.platformdirectory;itisregeneratedeachtimetheintegrationprocessisrunandsoshouldnotbeeditedmanually.
Parenttopic:DITAOpenToolkitDeveloperReference
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.
Parenttopic:DITAOpenToolkitDeveloperReference
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>
Parenttopic:CreatingDITA-OTplug-ins
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.
Parenttopic:CreatingDITA-OTplug-ins
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.
Parenttopic:CreatingDITA-OTplug-ins
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>
Parenttopic:CreatingDITA-OTplug-ins
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:
<?xmlversion="1.0"encoding="UTF-8"?>
<pluginid="com.example.brandheader">
<featureextension="dita.xsl.xhtml"file="xsl/header.xsl"/>
</plugin>
xsl/header.xsl:
<?xmlversion="1.0"encoding="UTF-8"?>
<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>
Parenttopic:CreatingDITA-OTplug-ins
ModifyingoraddinggeneratedtextGeneratedtextisthetermforstringsthatareautomaticallyaddedbythebuild,suchas"Note"beforethecontentsofa<note>element.
Thegeneratedtextextensionpointisusedtoaddnewstringstothedefaultsetofgeneratedtext.Thereareseveralreasonsyoumaywanttousethis:
Itcanbeusedtoaddnewtextforyourownprocessingextensions;forexample,itcouldbeusedtoaddlocalizedversionsofthestring"Userresponse"toaidinrenderingtroubleshootinginformation.
Itcanbeusedtooverridethedefaultstringsinthetoolkit;forexample,itcouldbeusedtoresettheEnglishstring"Figure"to"Fig".
Itcanbeusedtoaddsupportfornewlanguages(fornon-PDFtransformsonly;PDFrequiresmorecomplicatedlocalizationsupport).Forexample,itcouldbeusedtoaddsupportforVietnameseorGaelic;itcouldalsobeusedtosupportanewvariantofapreviouslysupportedlanguage,suchasAustralianEnglish.
dita.xsl.strings
Addnewstringstogeneratedtextfile.
Example:addingnewstrings
Firstcopythefilexsl/common/strings.xmltoyourplug-in,andeditittocontainthelanguagesthatyouareprovidingtranslationsfor("en-us"mustbepresent).Forthissample,copythefileintoyourplug-inasxsl/my-new-strings.xml.Thenewstringsfilewilllooksomethinglikethis:
<!--Providestringsformyplug-in;thisplug-insupports
English,Icelandic,andRussian.-->
<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:
<!--Maplanguageswithxml:lang="vi"orxml:lang="vi-vn"
tothetranslationsinthisplug-in.-->
<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).
Parenttopic:CreatingDITA-OTplug-ins
RelatedreferenceLanguagessupportedbythecoretoolkit
PassingparameterstoexistingXSLTstepsPlug-inscandefinenewparameterstobepassedfromtheAntbuildintoexistingXSLTpipelinestages,usuallytohavethoseparametersavailableasglobal<xsl:param>valueswithinXSLToverrides.
Tocreatenewparameters,createafileinsertParameters.xmlwhichcontainsoneormoreAnt<param>elements.Italsoneedsa<dummy>wrapperelementaroundtheparameters.Forexample,thefollowingparameterwillbepassedintotheXSLTfilewithavalueof${antProperty},butonlyifthatparameterisdefined:
<dummy>
<!--AnyAntcodeallowedinxslttaskispossible.Commonexample:-->
<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>
Parenttopic:CreatingDITA-OTplug-ins
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:
<?xmlversion="1.0"encoding="UTF-8"?>
<pluginid="com.example.samplejava">
<!--AddtheJARfiletotheDITA-OTCLASSPATH-->
<featureextension="dita.conductor.lib.import"file="com.example.sampleValidation.jar"/>
<!--IntegratetheAntcode-->
<featureextension="dita.conductor.target.relative"file="antWrapper.xml"/>
<!--DefinetheAnttargetthatiscalled,andthelocation(beforeconref)-->
<featureextension="depend.preprocess.conref.pre"value="validateWithJava"/>
</plugin>
antWrapper.xmlimportsthenewAntcode:
<?xmlversion="1.0"encoding="UTF-8"?>
<dummy>
<importfile="calljava-antcode.xml"/>
</dummy>
calljava-antcode.xml:
<?xmlversion="1.0"encoding="UTF-8"?>
<projectdefault="validateWithJava">
<targetname="validateWithJava">
<javaclassname="com.example.sampleValidation">
<!--Theclasswasaddedtodost.class.path(theDITA-OTclasspath)-->
<classpathrefid="dost.class.path"/>
</java>
</target>
</project>
Parenttopic:CreatingDITA-OTplug-ins
AddingdiagnosticmessagesPlug-inspecificwarninganderrormessagescanbeaddedtothesetofmessagessuppliedbytheDITA-OT.ThesemessagescanthenbeusedbyanyXSLToverride.
dita.xsl.messages
Addnewmessagestodiagnosticmessagefile.
Example
Toaddyourownmessages,createthenewmessagesinanXMLfilesuchasmyMessages.xml:
<dummy>
<!--Seeresource/messages.xmlforthedetails.-->
<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>
Parenttopic:CreatingDITA-OTplug-ins
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">
<!--...extensionshere-->
<requireplugin="com.example.primary"/>
</plugin>
Thefollowingplug-inwillonlybeinstalledifeithertheplug-inwithid="pluginA"ortheplug-inwithid="pluginB"areavailable.Ifneitherofthoseareinstalled,thecurrentplug-inwillbeignored.
<pluginid="pluginC">
<!--...extensionshere-->
<requireplugin="pluginA|pluginB"importance="optional"/>
</plugin>
Parenttopic:CreatingDITA-OTplug-ins
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>
Parenttopic:CreatingDITA-OTplug-ins
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>
Parenttopic:CreatingDITA-OTplug-ins
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>
Parenttopic:CreatingDITA-OTplug-ins
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".
Parenttopic:DITAOpenToolkitDeveloperReference
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
<?xmlversion="1.0"encoding="UTF-8"?>
<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
<?xmlversion="1.0"encoding="UTF-8"?>
<xsl:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="2.0">
<!--ChangepagesizetoA4-->
<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
<?xmlversion="1.0"encoding="UTF-8"?>
<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">
<!--Movefiguretitletotopanddescriptiontobottom-->
<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
<?xmlversion="1.0"encoding="UTF-8"?>
<varsxmlns="http://www.idiominc.com/opentopic/vars">
<!--Removedotfromlistnumber-->
<variableid="OrderedListNumber"><paramref-name="number"/></variable>
<!--Changeunorderedlistbullettoanemdash-->
<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.
Parenttopic:DITAOpenToolkitDeveloperReference
InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.
include.rellinks
Spaceseparatedlistoflinkrolestobeoutput;valuetoken#defaultdenotesdefaultrolevalue.Propertydefaultvaluedependsontransformationtype.Definedbyargs.rellinks,butmaybeoverriddendirectly.
Parenttopic:DITAOpenToolkitDeveloperReference
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.
Parenttopic:DITAOpenToolkitDeveloperReference
ExtendedfunctionalityParenttopic:DITAOpenToolkitDeveloperReference
Codereferenceprocessing
Charsetdefinition
DITA-OTsupportsdefiningthecodereferencetargetfileencodingusingtheformatattribute.Thesupportedformatis:
format(";"space*"charset="charset)?
Ifcharsetisnotdefinedsystemdefaultcharsetwillbeused.Ifcharsetisnotrecognizedorsupported,DOTJ052Eerroristhrownandsystemdefaultcharsetisusedasafall-back.
<coderefhref="unicode.txt"format="txt;charset=UTF-8"/>
Linerangeextraction
Codereferencecanextractonlyagivenlinerangeswithline-rangepointerintheURIfragment.Theformatis:
uri("#line-range("start(","end)?")")?
Startandendlinenumbersstartfrom1andareinclusive.Ifendrangeisomitted,rangeendsinlastlineofthefile.
<coderefhref="Parser.scala#line-range(5,10)"format="scala"/>
Onlylinesfrom5to10willbeincludedintheoutput.
RFC5147
DITA-OTimplementslinepositionandrangefromRFC5147.Theformatforlinerangeis:
uri("#line="start?","end?)?
Startandendlinenumbersstartfrom0andareinclusiveandexclusive,respectively.Ifthestartrangeisomitted,rangestartsfromthefirstline;ifendrangeisomitted,rangeendsinlastlineofthefile.Theformatforline
positionis:
uri("#line="position)?
Positionlinenumberstartsfrom0.
<coderefhref="Parser.scala#line=4,10"format="scala"/>
Onlylinesfrom5to10willbeincludedintheoutput.
DITAandDITA-OTresourcesInadditiontotheDITA-OTdocumentation,thereareotherresourcesaboutDITAandtheDITA-OTthatyoumightfindhelpful.
DITA-OTprojectpageatdita.xml.orgTheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.
Yahoo!dita-usersgroupThislist-servisavitalresourcefortheDITAcommunity.Peoplepostregularly,bothaskingforandofferinghelp.Whilethearchivedmessagescanbedifficulttosearch,thisisatreasuretroveofinformation.
HomepagefortheOASISDITATechnicalCommitteeTheOASISDITATechnicalCommitteedevelopstheDITAstandard.
Web-basedresourcesTherearemanyvitalDITAresourcesonline,includingtheYahoo!dita-usersgroupandtheDITA-OTprojectpageatdita.xml.org.
developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.
Web-basedresourcesTherearemanyvitalDITAresourcesonline,includingtheYahoo!dita-usersgroupandtheDITA-OTprojectpageatdita.xml.org.
DITA-OTprojectpageatdita.xml.org
TheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.
Yahoo!dita-usersgroup
TheDITA-OTprojectpageatdita.xml.orgprovidesnewsaboutthelatesttoolkitbuilds,plansforthenextmilestonerelease,andotherrapidly-changinginformation.Italsocontainsreleasenotesforallpastandupcomingreleases.
HomepagefortheOASISDITATechnicalCommittee
TheOASISDITATechnicalCommitteedevelopstheDITAstandard.
Parenttopic:DITAandDITA-OTresources
developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.
IntroductiontotheDarwinInformationTypingArchitecture
SpecializingtopictypesinDITA
SpecializingdomainsinDITA
FrequentlyAskedQuestionsabouttheDarwinInformationTypingArchitecture
WhyuseDITAtoproduceHTMLdeliverables?
DesignpatternsforinformationarchitecturewithDITAmapdomains
MigratingHTMLtoDITA,Part1:SimplestepstomovefromHTMLtoDITA
MigratingHTMLtoDITA,Part2:Extendthemigrationformorerobustresults
TransformEclipsenavigationfilestoDITAnavigationfiles
Parenttopic:DITAandDITA-OTresources
generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.
Background
Thisisanissueinthefollowingsituations:
TheDITAmapisinadirectorythatisapeertodirectoriesthatcontainreferencedobjects.
TheDITAmapisinadirectorythatisbelowthedirectoriesthatcontainthereferencedobjects.
Let'sassumethatthedirectorystructurefortheDITAcontentlookslikethefollowing:
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