DITAOpenToolkit1.8.4ThisdocumentdescribestheDITAOpenToolkitproject—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,versionorlaterinstalled.
EnsurethatyouhaveHTMLHelpWorkshopinstalled,ifyouwanttogenerateHTMLHelp.
Procedure
1. Downloadthefull-easypackagefromSourceForge.
Operatingsystem Filename
LinuxorMacOSX
DITA-OT_full_easy_install_bin.tar.gz
Windows DITA-OT_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-OT1.6.M5\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-OT1.6.M5\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
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).
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.
DITAOpenToolkitRelease1.8
DITA1.2SpecificationSupportDITAOpenToolkit1.8.4supportstheDITA1.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
GeneralEnhancementsandChanges
Preprocessing
Additionalvalidationhasbeenaddedtochecke.g.elementIDuniqueness,andxml:langandURIsyntax.
BundledFOPhasbeenupdatedfrom1.0to1.1.
Migrationfrompreviousreleases
Stylesheetsforthefollowingtranstypeshavemovedtoplug-inspecificfolders:
eclipsehelp
htmlhelp
javahelp
odt
xhtml
Preprocessing
ThefollowingdeprecatedAntpropertieshavebeenremoved:
dita.script.dir,use${dita.plugin.id.dir}instead
dita.resource.dir,use${dita.plugin.org.dita.base.dir}/resourceinstead
dita.empty
args.message.file
XHTML
XSLTJavaextensionImgUtilshasbeenremovedfromstylesheetsandbeenreplacedwithpreprocessingmoduleImageMetadataModule.TheoldImgUtilsJavaclassesarestillincludedinthebuild.
ThefollowingdeprecatedXSLTstylesheetshavebeenremoved:
artwork-preprocessor.xsl
otdita2fo_frontend.xsl
ThefollowingdeprecatedXSLTtemplateshavebeenremoved:
insertVariable.old
ThefollowingdeprecatedXSLTmodeshavebeenremoved:
layout-masters-processing
toc-prefix-text,usetocPrefixmodeinstead
toc-topic-text,usetocTextmodeinstead
Linkgenerationhasbeensimplifiedbyremovingdeprecatedargumentsinfavourofargs.rellinks.ThefollowingdeprecatedAntpropertieshavebeenremoved:
args.fo.include.rellinks
ThefollowingXSLTparametershavebeenremoved:
antArgsIncludeRelatedLinks
disableRelatedLinks
AcalltoanamedtemplatepullPrologIndexTerms.end-rangehasbeenaddedtoprocessTopic*templatestohandletopicwideindexranges.
LegacyPDF
ThefollowingdeprecatedXSLTstylesheetshavebeenremoved:
dita2fo-shell_template.xsl
topic2fo-shell.xsl
ODT
Linkgenerationhasbeensimplifiedbyremovingdeprecatedargumentsinfavourofargs.rellinks.ThefollowingdeprecatedAntpropertieshavebeenremoved:
args.odt.include.rellinks
ThefollowingXSLTparametershavebeenadded:
include.rellinks
ThefollowingXSLTparametershavebeenremoved:
disableRelatedLinks
Issues
ThefollowingitemsareincludedinDITAOpenToolkitRelease1.8.IssuenumberscorrespondtothetrackingnumberintheGitHubissuestracker.
Featurerequests
#1406BundleFOP1.1(milestone1)
#1447Movestylesheetsandresourcefilestoplug-infolder(milestone1)
#1449AddsupportforSlovenian(milestone1)
#1453Addimagemetadatafilter(milestone1)
#1435Addvalidationfiltertodebug-filterstep
#1455Removedeprecatedfeatures
#1460"GetString"templateshoulduseparameterinsteadofvariable
#1461MovefilelistgenerationtoAnt
#1465Newdoctopiclistingnon-standardtweakstopreprocessedfiles
#1480Correctingvaluesforthe@relcolwidthattribute
#1492Linerangeextensiontocoderefprocessing
#1494Moveintegratorconfigurationtolib/configuration.properties
#1495Removeancientdocdirectories
Bugs
#1425XHTMLflaggingincludedbeforeimports(milestone1)
#1428Topiclevelcalculatedincorrectlyforappendices(milestone1)
#1427Fixtextoverflowissueinlot/lofentrieswithlongtitles(milestone1)
#1430PDFtransformation:ProblemswithindexinOT1.7(milestone1)
#1432startcmd.shbrokenin1.7(milestone1)
#1433Profilingfilterincludedmultipletimes(milestone1)
#1437FatalUTF-8errorin.job.xml(milestone1)
#1456XHTMLBuildfailedwhenreferencingsubjectschemeindifferentfilepath(milestone1)
#1080Indexpagerangeissues(milestone2)
#1423FormattingglitchinPDFindex(milestone2)
#1468ReferencetoremoteimagedoesnotappearinPDF(milestone2)
#1469@outputclassand@classvaluesnotpassedfrom<chhead>to<tr>inXHTMLoutput(milestone2)
#1472PDFoutput:whitespacenotpreservedinmsgblockelement(milestone2)
#1475ErrorreceivedinconsoledoesnotpointcorrectlytolocationofpublishedDITAMap(milestone2)
#1477Tables:usingpercentageincolwidthvalues[PDF2plugin](milestone2)
#1464Flaggingasimpletablerowthrowsoff@keycolcountingbug(milestone2)
#1459LinknotcreatedintheXHTMLoutputforaxref/@keyrefelement
#1473Troffoutputnotworkinginlatestbuildbugtroff
#1498Whitespacewillbreaktocjs
#1519LatestcodeindevelopbranchfailstobuildPDF
#1528PDFfailswhentopicreferencedwithandwithouttopicID(maintenance1)
#1529NPEwhentopicheadhas@copy-toand@chunk="to-content"(maintenance1)
#1535SpecializedclasscannotbehandledduringXMLparsing(maintenance1)
#1537Whitespaceissuewhen@conrefisprecededbyalinefeedinmap<title>(maintenance1)
#1538Incorrecthandlingoftopicsoutsideofmappath(maintenance1)
#1531CSSlinkgeneratedwithbackslashonWindows(maintenance2)
#1532Keyreflinkgeneratedwithbackslashand%5ConWindows(maintenance2)
#1540Addmissing@classattributeto<navref>inchunkingphase(maintenance2)
#1547startPageNumberingmissingfromsomepagesequence(maintenance2)
#1073Someelementsarenothandledcorrectlyintrofftransform(maintenance3)
#1175pdf2plugin:PDFtransformproducesinvalidFOdocwithDITAVAL(flagonsimpletable)(maintenance3)
#1234pdf2plugin:Noteimagepathbrokenfor"other"notetype(maintenance3)
#1373CellsofaPropertiestablemisalignedinPDFoutputifValue
columnismissing(maintenance3)
#1563path2projectgeneratedPIisinvalidincopy-tofile(maintenance3)
#1570pdf2plugin:'Bodyfirstheader'variabledoesnotsupport'prodname'parameter(maintenance3)
#1571pdf2plugin:topleveltopictitlesstyledasnormaltext(maintenance3)
#1581pdf2plugin:ChangebarsfromDITAVALcrashFOP(maintenance3)
#1584Addbasictablesupporttotroff#1073(maintenance3)
#1585Propertiestablecellmisallignedifnovaluecolumn#1373(maintenance3)
#1603XSDschemaforMachineryTaskdoesnotallowattributesinprelreqselement(maintenance3)
#1597mappullgeneratesDOTX021EandDTX025Eforresourceonlytopicrefstopngfiles(maintenance4)
#1604Failedtoreadjobfile:XMLdocumentstructuresmuststartandendwithinthesameentity.(maintenance4)
#1622UpdatesomeXSDfixesthatwerefoundbydevelopersfromPTC.Also(maintenance4)
#1626DIITA-OT1.8.M2\plugins\org.dita.pdf2\lib\fo.jardoesnotincludethexepdirectory(maintenance4)
#1639xhtmloutputreplacesbackslashin@hrefwithescapedcharacter(DOT1.8M2)(maintenance4)
#1640ODTpublishingdoesn'twork(DITAOT1.8M2)(maintenance4)
#1641LegacyPDFdoesn'twork(DITAOT1.8M2)(maintenance4)
#1645ConversionofFiletoURLisnotproperlydoneinseveralplaces(maintenance4)
#1647IllegalfileseparatorusedincreatedURI(DITAOT1.8M2)(maintenance4)
DITA1.2SpecificationSupportDITAOpenToolkit1.8.4supportstheDITA1.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.
ApplicationTestedversion
AntAnt1.7.1
Ant1.8.2,1.8.3,1.8.4
ICUforJava
ICU4J3.4.4
ICU4J49.1
JDK
IBM1.6
OpenJDK1.7
Oracle1.6
Operatingsystem
MacOSX10.6
MacOSX10.7
SLES10
WindowsXP
Windows7
XMLparserXerces2.9.0
Xerces2.11.0
Saxon6.5
XSLTprocessor
Saxon9
Saxon-B9.1
Saxon-PE/EE9.3
Xalan-J2.6
Xalan-J2.7
Xalan-J2.7.1
Note:TheDITA-OTdoesnotofficiallyrequireXSLT2.0,sincesomeusersarereliantonXalan.
Parenttopic:OverviewoftheDITAOpenToolkit
InstallingtheDITAOpenToolkitYoucaninstalltheDITAOpenToolkit(DITA-OT)onLinux,MacOSX,andWindows.TheprocessforinstallingandsettinguptheDITA-OTdependsonthetypeofdistributionpackagethatyouselect.
DistributionpackagesTheDITAOpenToolkitisdistributedinthreepackages:minimal,standard,andfull-easy-install.ThesourcecodeisavailablebothasaGitrepositoryandaZIPfile.
PrerequisitesoftwareTheprerequisitesoftwarethattheDITA-OTrequiresdependsonthetypeofdistributionpackagethatyouintendtoinstallandthetypesoftransformationsthatyouwanttouse.
Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.
Parenttopic:DITAOpenToolkitUserGuide
DistributionpackagesTheDITAOpenToolkitisdistributedinthreepackages:minimal,standard,andfull-easy-install.ThesourcecodeisavailablebothasaGitrepositoryandaZIPfile.
Minimalpackage
Thispackageisdesignedforvendorsthatembedthetoolkitwithinaproduct.Itcontainsallofthecoreprocessingcode:CSSandXSLTfiles,Antbuildscripts,Javacode(dost.jar),resourcefiles,andtheOASISDITADTDsandSchemas.UsersneedtohavetheirownversionsofAntandotherlibraries;theyalsoneedtosetupenvironmentvariablesforeachlibrary.TheonlyexternalfilesthatareincludedaretheDTDsandSchemas,alongwiththefollowingopen-sourcelibraries:
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.4
ApacheXerces,version2.11.0
Theminimalpackagehasthefollowingfilenames:
DITA-OT1.8.4_minimal_bin.zip
DITA-OT1.8.4_minimal_bin.tar.gz
Standardpackage
Thispackageisdesignedforpeoplewhowantthecoretoolkitfunctionality,butwhoalreadyhavelocally-installedcopiesofAntandotherrequiredtools.Itcontainseverythingintheminimalpackage,plusdocumentation,democode(forexample,legacysupportfortheoldbookmap),sampleAntscripts,andsampleDITAfiles.Thestandardpackageincludesthefollowingopen-sourcelibraries:
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.4
ApacheXerces,version2.11.0
Thestandardpackagehasthefollowingfilenames:
DITA-OT1.8.4_standard_bin.zip
DITA-OT1.8.4_standard_bin.tar.gz
Full-easy-installpackage
hispackageisdesignedforuserswhowantthesimplestinstallationexperience.InadditiontothecoreDITA-OTcodeandtheexternallibrariesthatareintheminimalandstandardpackages,itcontainsApacheAntandFOP.Thefull-easy-installpackagealsocontainsbatchfilesdesignedtosetupabuildenvironmentusingthosetools,aswellasascriptsforaguideddemooftheDITA-OT.Thefull-easy-installpackageincludesthefollowingexternallibraries:
ApacheAnt,version1.8.4
ApacheCatalogResolver,version1.1
ApacheCommonsCodec,version1.4
ApacheFOP,version1.0
ICUforJava,version49.1
ApacheXerces,version2.11.0
Saxon,version9.1
Thefull-easy-installpackagehasthefollowingfilenames:
DITA-OT1.8.4_full_easy_install_bin.zip
DITA-OT1.8.4_full_easy_install_bin.tar.gz
Parenttopic:InstallingtheDITAOpenToolkit
RelatedinformationDITAOpenToolkitdistibutionpackagedownloadsDITAOpenToolkitsource
PrerequisitesoftwareTheprerequisitesoftwarethattheDITA-OTrequiresdependsonthetypeofdistributionpackagethatyouintendtoinstallandthetypesoftransformationsthatyouwanttouse.
SoftwarerequiredforcoreDITA-OTprocessing
TheDITA-OTrequiresthefollowingsoftwareapplications:
JREorJDK,version6orlater
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.ItmustbecompliantwithXSLT1.0.TheDITA-OTistestedwithbothSaxonandXalan-J.YoucandownloadSaxon,version9.1fromhttp://saxon.sourceforge.net/andXalan-J,version2.7.1orlaterfromhttp://xml.apache.org/xalan-j/downloads.html.
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
Installingthefull-easy-installpackageForthesimplestinstallationexperience,installthefull-easy-installpackage.ThispackagecanbeinstalledonLinux,MacOSX,andWindows.ItcontainseverythingthatyouneedtoruntheDITA-OTexceptforJava.
Beforeyoubegin
EnsurethatyouhaveJavaJREorJDK,version6orlaterinstalled.
EnsurethatyouhaveHTMLHelpWorkshopinstalled,ifyouwanttogenerateHTMLHelp.
Procedure
1. Downloadthefull-easypackagefromSourceForge.
Operatingsystem Filename
LinuxorMacOSX
DITA-OT1.8.4_full_easy_install_bin.tar.gz
Windows DITA-OT1.8.4_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,version6orlater
XSLTprocessor.YoucanuseeitherSaxon,version9.1orlater,orXalan-J,version2.7.1orlater.
Inaddition,determinethespecificDITA-OTtransformationsthatyouintendtosupportandensurethatyouhavetheprerequisitesoftwareinstalledforthem.
Formoreinformation,seePrerequisitesoftwareandTestedplatformsandtools.
Procedure
1. DownloadtheminimalorstandardpackagefromSourceForge.
Package FilenameMinimal DITA-OT1.8.4_minimal_bin.tar.gz
StandardDITA-OT1.8.4_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.4.jar:$CLASSPATH
8. Optional:IfyouuseAnt,version1.8orlater,setuptheCLASSPATHenvironmentvariabletoincludeApacheXerces.
exportCLASSPATH=<xerces_dir>/xercesImpl.jar:<xerces_dir>/xml-apis.jar:$CLASSPATH
9. SetuptheXSLTprocessor:
ProcessorAction
Saxon
SetuptheCLASSPATHenvironmentvariabletoincludetheSaxonJARfiles,forexportCLASSPATH=<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
XalanSetuptheCLASSPATHenvironmentvariabletoincludetheXalanJARfiles,forexample:
exportCLASSPATH=<xalan_dir>/xalan.jar:$CLASSPATH
10. Optional:Forindexprocessing,setupICUforJava.exportCLASSPATH=<icu4j_dir>/icu4j.jar:$CLASSPATH
11. Optional:ForJavaHelp,settheJHHOMEenvironmentvariable.exportJHHOME=<javahelp_dir>
12. Optional:ForPDFoutput,setuptheXSL-FOprocessor:
Processor Action
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-OT1.8.4$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,version6orlater
XSLTprocessor.YoucanuseeitherSaxon,version9.1orlater,orXalan-J,version2.7.1orlater.
Inaddition,determinethespecificDITA-OTtransformationsthatyouintendtosupportandensurethatyouhavetheprerequisitesoftwareinstalledforthem.
Formoreinformation,seePrerequisitesoftwareandTestedplatformsandtools.
Procedure
1. DownloadtheminimalorstandardpackagefromSourceForge.
Package FilenameMinimal DITA-OT1.8.4_minimal_bin.zip
StandardDITA-OT1.8.4_standard_bin.zip
Forproductionuse,werecommendthatyouusethelateststablerelease.
2. Extractthecontentsofthepackageintoaninstallationdirectory.Forexample,C:\pkg\DITA-OT1.8.4.
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.4.jar;%CLASSPATH%
8. Optional:IfyouuseAnt,version1.8orlater,setuptheCLASSPATHenvironmentvariabletoincludeApacheXerces.
setCLASSPATH=<xerces_dir>\xercesImpl.jar;<xerces_dir>\xml-apis.jar;%CLASSPATH%
9. SetuptheXSLTprocessor:
ProcessorAction
Saxon
SetuptheCLASSPATHenvironmentvariabletoincludetheSaxonJARfiles,forsetCLASSPATH=<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
XalanSetuptheCLASSPATHenvironmentvariabletoincludetheXalanJARfiles,forexample:
setCLASSPATH=<xalan_dir>\xalan.jar;%CLASSPATH%
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:
Processor Action
FOP
AddtheFOPinstallationdirectorytothelocal.propertiesfileasthefop.homeproperty,for
example:fop.home=C:\\ProgramFiles\\fop
RenderX
AddtheRenderXinstallationdirectorytothelocal.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-OT1.8.4>ant-fsamples\ant_sample\sample_all.xml
ThegeneratedoutputiswrittentotheDITA-dir\out\samplesdirectory.Thefollowingoutputformatsaregenerated:
Docbook
Eclipsehelp
HTMLHelp
ODT
JavaHelp
TocJS
TROFF
XHTML
PublishingDITAcontentYoucanuseeitherAntorthecommand-linetooltotransformDITAcontenttothevariousoutputformatsthataresupportedbytheDITAOpenToolkit(DITA-OT).
DITA-OTtransformationsTheDITAOpenToolkit(DITA-OT)shipswithseveralcoretransformations.EachcoretransformationrepresentsanimplementationofallprocessingthatisdefinedbyOASISintheDITAspecification.
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.
DITAtoHTMLHelp(CHM)ThehtmlhelptransformationgeneratesHTMLoutput,CSSfiles,andthecontrolfilesthatareneededtoproduceaMicrosoftHTMLHelpfile.
DITAtolegacyPDFtransformationThelegacypdftransformationproducesaPDFusingthedemoPDFbuild.Thistransformationisdeprecated.
DITAtoOpenDocumentTypeTheodttransformationproducesoutputfilesthatusetheOpenDocumentformat,whichisusedbytoolssuchasOpenOffice.
DITAtoPDF(PDF2)Thepdf(orpdf2)transformationgeneratesPDFoutput.
DITAtoRichTextFormatThewordrtftransformationproducesanRTFfileforusebyMicrosoftWord.
DITAtoTocJSThetocjstransformationgeneratesXHTMLoutput,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
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
DITAtolegacyPDFtransformationThelegacypdftransformationproducesaPDFusingthedemoPDFbuild.Thistransformationisdeprecated.
ThefirstversionsofthetoolkitcamewiththedemoPDFbuild,whichwasreplacedbythemorerobustPDFplug-in(alsoknownasPDF2)inrelease1.4.3.ThedemoPDFbuildisnolongermaintainedbytheDITA-OTdevelopers,althoughthetoolkitincludesitinordertosupportoldercustomizationsandbuildscriptsthatextendedthecode.
Parenttopic:DITA-OTtransformations
RelatedreferenceAntparameters:LegacyPDFtransformation
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
DITAtoTocJSThetocjstransformationgeneratesXHTMLoutput,aframeset,andaJavaScript-basedtableofcontentswithexpandableandcollapsibleentries.ThetransformationwasoriginallycreatedbyShawnMcKenzieasaplug-inandwasaddedtothedefaultdistributioninDITAOT,release1.5.4.
ThetocjstransformationwasupdatedsothatitproducesXHTMLoutputandusesadefaultframeset.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:XHTMLtransformationCommand-linetoolparameters:XHTMLtransformation
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="xhtml"/>
</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.
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
ThefollowingcommandgeneratesXHTMLoutputforthesequence.ditamapfileandspecifiestheoutputiswrittentothetestdirectory
java-jarlib/dost.jar/i:samples/sequence.ditamap/outdir:test/transtype:xhtml
Parenttopic:PublishingDITAcontentfromthecommand-linetool
RelatedconceptsCommand-linetool
RelatedreferenceCommand-linetoolparameters
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-andXHTML-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-andXHTML-basedtransformations,forexample,EclipseHelp,HTMLHelp,andTocJS.
Table1.Supportedlanguages:HTML-andXHTML-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.Thisinformationalsoiswrittentoalogfile.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"isnotarecognizedtransformationtype.Supportedtransformationtypesare
Defaulttransformationtypesthatshipwiththetoolkitincludexhtml,eclipsehelp,pdf(orpdf2),tocjs,htmlhelp,javahelp,odt,
DOTA001F Fatal docbook,eclipsecontent,eclipsehelp,htmlhelp,javahelp,net.sourceforge.dita-ot.html,odt,pdf,pdf2,tocjs,troff,wordrtf,xhtml.
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.
DOTA010E Error
TheApacheFOPprogramcannotbefoundinthedefaultlocation.PleaseplaceFOPintothedefaultdirectorydemo/fo/fop/orupdatethebuildfiletosupportyourlocalconfiguration.
Bydefault,theDITA-OTexpectstofindApacheFOPinthedirectoryinsideofthePDFplug-in.Ifyouareusinganalternaterenderer,orifyouhaveplacedFOPinadifferentdirectory,youwillneedtoupdateyourconfigurationaccordingly.
DOTA011W WarningArgument"%1"isdeprecated.Thisargumentisnolongersupportedinthetoolkit.
DOTA012WWarning Argument"%1"isdeprecated.Pleaseusetheargument"%2"instead.
DOTA066F Fatal CannotfindtheuserspecifiedXSLTstylesheet'%1'.
AnalternatestylesheetwasspecifiedtoruninplaceofthedefaultXSL-FOoutputprocess,butthatstylesheetcouldnotbeloaded.Pleasecorrecttheparametertospecifyavalidstylesheet.
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.
Parameter'%1'wasspecifiedwithoutavalue.Parameterstothecommandline See
DOTJ003F Fatal toolshouldusethesyntax/parameter:value.
parametersparametersandvalues.
DOTJ004F Fatal
Cannotcreatetemporaryprocessingdirectory'%1'.Pleaseensurethatyouhavepermissiontocreatethedirectory'%1'.
Thetransformwasunabletocreateatemporaryprocessingdirectory;thisisusuallycausedbyaccountcontrolsettingsthatpreventcreatingatemporarydirectoryinthespecifiedlocation.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'.Themodifiedresultmaynotbeconsumedbythefollowingstepsinthetransform
Thetransformwasunabletocreatefilesproperlyduringthe
pipeline.Checktoseewhetherthefileislockedbysomeotherapplicationduringthetransformationprocess.
transform;resultsmaynotbeasexpected.
DOTJ012F Fatal Failedtoparsetheinputfile'%1'.TheXMLparserreportedthefollowingerror:
Thismessagemayindicateaninvalidinputfile(suchasaccidentallyspecifyingaPDFfileasinputratherthanaDITAmapfile),aninputfilethatuseselementswhicharenotallowed,arenotpartoraDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.
DOTJ013E ErrorFailedtoparsethereferencedfile'%1'.TheXMLparserreportedthefollowingerror:
Thismessagemayindicateareferencetoaninvalidfile(suchasaccidentallyreferencingaPDForunknownXMLfileasifitwasDITA),areferencedfilethatuseselementswhicharenotallowed,orareferencedDITAfilethathaserrorsandcannotbeparsedasXML.YoucouldalsobeusingaspecializedDITAdocumenttypethatneedsexternalplug-insinordertobeparsedcorrectly.ThemessageissuedbytheXMLparsershouldprovideadditionalinformationtohelpdiagnosethecause.Anempty<indexterm>element
DOTJ014W Warning Foundanindextermelementwithnocontent.Settingthetermto***.
wasfound,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,andaditavalexcludesallcontentbasedon
Eithertheinputfileortheditavalfileshouldchange,otherwiseyourbuildisexplicitlyexcludingallcontent.
thoseconditions.
DOTJ023E Error Failedtogetthespecifiedimagefile'%1',soitwillnotbeincludedwithyouroutput.
Checkwhethertheimageexistsinthesourcelocationoralreadyexistsintheoutputdirectory.
DOTJ025E Error
Theinputtothe"topicmerge"transformprocesscouldnotbefound.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.
Thismessageshouldonlyappearinthefollowingcases:
DOTJ026E Error
The"topicmerge"didnotgenerateanyoutput.Correctanyearliertransformerrorsandtrythebuildagain,orseetheDITA-OTUserGuideforadditionalcauses.
ThismessageshouldonlyappearifanAntbuildorplug-inisdirectlycallingthetoolkit'stopicmergemodule,orifearliererrorsresultedinproblemswithsomeofthecontent.Ifthetopicmergemoduleiscalledcorrectly,thenthisindicatesaprogramerrorthatshouldbe
reportedtotheDITA-OTdevelopmentteam,atbugandfeaturetracker
DOTJ028E Error
Noformatattributewasfoundonareferencetofile'%1',whichdoesnotappeartobeaDITAfile.IfthisisnotaDITAfile,settheformatattributetoanappropriatevalue,otherwisesettheformatattributeto"dita".
Whenreferencinganon-DITAfile,theformatattributeshouldindicatethetypeoffilereferenced(suchas"html"forHTMLtopicsor"pdf"forPDFfiles).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'doesnothaveaDOCTYPE
DITAprocessingisbasedonclassattributesdefinedforeveryelement.UsuallythesearedefaultedintheDTDorSchema;ifnoDTDorSchema
declaration,pleasemakesurethatallclassattributesarepresentinthefile.
isused,theclassattributesmustbeexplicitlyincludedinthemaportopic.
DOTJ035F Fatal
Thefile"%1"referencedby"%2"isoutsidethescopeoftheinputdita/mapdirectory.Ifyouwanttolowertheseveritylevel,pleaseusetheAntparameter'outer.control',andsetthevalueto"warn"or"quiet".Otherwise,movethereferencedfile"%1"intotheinputdita/mapdirectory.
Thisoutsidethescopeofthemap;forexample,ifthemaininputmapreferencesdirectory/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,theclassattributesmustbe
explicitlyincludedinthemaportopic.
DOTJ038E Error
Thetag"%1"isspecializedfromunrecognizedmetadata.Pleasemakesurethattag"%1"isspecializedfromanexistingmetadatataginthecoreDITAvocabulary.
Thisappearstoindicateanerrorincreatingspecializedmetadataelements.PleaseverifythatthedocumenttypeyouareusingiscompleteandcomplieswithDITASpecializationrules.
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.
Theconrefpushfunctionistryingto
Thetargetforaconrefpushactiondoesnotexist;pleasemakesurethatthesyntaxiscorrectandthatthetargetexists.Seethetopicon
DOTJ043W Warning replaceanelementthatdoesnotexist(element"%1"infile"%2").
basedaddressingspecificationfordetailsontheexpectedsyntax.Ifthesyntaxiscorrect,itispossiblethatthetargetwasfilteredoutofyourbuildusingaDITAVALfile.
DOTJ044W Warning
Thereisaredundantconrefaction"pushbefore".Foundinfile="%1",element="%2".Pleasemakesurethat"mark"and"pushbefore"occurinpairs.
PleaseseethetopiconPushfordetailsonexpectedsyntaxforthisfunction.
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.
DOTJ051E Error Unabletoloadtargetforcoderef"%1".
Thetargetforacoderefelement,whichspecifiesanexternaltext-basedfile,couldnotbelocatedorloaded.Pleaseverifythatthereferenceiscorrect.
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"are
Bydefault,theDITA-OTsupportstheextensions"dita"and"xml"forDITAtopics,asmandatedbytheDITASpecification.Pleaseverifythat
supportedforDITAtopics. yourtopicsuseoneoftheseextensions,orconfigurethetoolkittoallowadditionalextensions.
DOTJ054E Error Unabletoparseinvalid%1attributevalue"%2"
DOTJ055E Error Invalidkeyname"%1". DOTJ056E Error Invalidxml:lang"%1".
DOTJ057E Error Theidattributevalue"%1"isnotuniquewithinthetopicthatcontainsit.
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,oranotherDITAmap(whichwillpresumablyalsobeconvertedto
anEclipseTOC).
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.Tofixthetableofcontents,specifyanavigationtitleinyour
DOTX008WWarningFile'%1'cannotbeloaded,andnonavigationtitleisspecifiedforthetableofcontents.
maporensurethatthereferencedfileislocalandcanbeaccessed.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(whichwillremovethetargetbeforeconrefprocessingruns).
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'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathto
thetemporarydirectoryratherthantotheoriginal.
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'),insteadoftheoriginalextensionusedbythefile;itmayalso
includeapathtothetemporarydirectoryratherthantotheoriginal.
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,whichmaycauseyourlinkstosort
inappropriately.
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.Thereferencedfiledidnotspecifyanylinktextfor
DOTX027WWarning Unabletoretrievelinktextfromtarget:'%1'.
generatedmap-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.Thebuildattemptedtoaccessthespecifiedfileinorderto
DOTX031E Error Thefile%1isnotavailabletoresolvelinkinformation.
retriveatitleorshortdescription,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>elementspecifiestype="fn",whichindicatesalink
DOTX035E Error Unabletogeneratethecorrectnumberforacrossreferencetoafootnote:'%1'
toafootnote,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.Thecontentwillbehiddenwhen
thedraftparameterisnotactive.
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"andagainwithnospecifiedrole,itmayshowupas
boththe"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,youmayneedtorecompiletheCHMfileaftermakingthefileavailable.
ThebuildwillnotlookforpeerorexternaltopicsbeforecompilingyourCHMfile,sotheymaynotbeincluded.IfyouarereferencinganactualHTMLfilethatwillnotbeavailable,itcannotbeincludedintheproject,andyoushouldsetthetocattributeto"no"onyour
topicrefelement.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.
DOTX053E Error
Aelementthatreferencesanothermapindirectlyincludesitself,whichresultsinaninfiniteloop.Theoriginalmap
Thiswilloccurifamapreferencesanothermap,andthenthatsecondmap(oranotherfurthernestedmap)referencestheoriginalmap.The
referenceisto'%1'. resultisaninfinitenestingofmaps;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.
DOTX057WWarning
Thelinkorcrossreferencetarget'%1'cannotbefound,whichmaycauseerrorscreatinglinksorcrossreferencesinyour
ThelinkappearstousevalidsyntaxtoreferenceaDITAelement,butthatelementcannotbefound.Pleaseverify
outputfile. thattheelementexists,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.Thehrefattributeonatopicrefelementshouldonlyreferencetopiclevelelements.
AccordingtotheDITASpecification,referencesfrommapsshouldeithergotoDITAMaps,DITATopics,DITAresource.Referencesbelowthetopiclevelshouldonlybemadefromcrossreferences(using<xref>orsimilar)inside
ofatopic.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.
DOTX066WWarningTemplate"%1"isdeprecated.Removereferencestothistemplatefromyour
ThismessageindicatesthatyourcustomXSLTorplug-insrelyontemplatesthatwillberemovedinanupcomingrelease.Typicallythisoccurs
customXSLTorplug-ins. whenanamedtemplatehasbeenconvertedtoamodetemplate;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 Fatal Topicreference(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.
Parenttopic:Errormessagesandtroubleshooting
OthererrormessagesInadditiontoerrormessagesgeneratedbytheDITAOpenToolkit,youmightalsoencountererrormessagesgeneratedbyJavaorothertools.
OutofMemoryerror
Insomecases,youmightreceiveamessagestatingthebuildhasfailedduetoanOutofMemoryerror.Trythefollowingapproachestoresolvetheproblem:
1. (Forcustom-configuredenvironments,nottheDITA-OTFullEasyInstall)IfyouuseXalanasthedefaultXSLTprocessor,switchtoSaxon.
2. IncreasethememoryavailabletoJava;seeIncreasingJavamemoryallocation.
3. Reducememoryconsumptionbysettingthegenerate-debug-attributesoptiontofalse.Thisoptionissetinthelib/configuration.propertiesfile.Thiswilldisabledebugattributegeneration(usedtotraceDITA-OTerrormessagesbacktosourcefiles)andwillreducememoryconsumption.
4. Setdita.preprocess.reloadstylesheetAntpropertytotrue.ThiswillallowtheXSLTprocessortoreleasememorywhenconvertingmultiplefiles.
5. Runthetransformationagain.
java.io.IOException:Can'tstoreDocument
AfterrunningaJavaHelptransformation,youmayreceiveajava.io.IOException:Can'tstoreDocumentmessage.
ThisproblemoccurswhenHTMLfilesunrelatedtothecurrenttransformationarefoundintheoutputdirectory.Deletethecontentoftheoutputdirectoryandrunthetransformationagain.
StackOverflowerror
Ifyoureceiveanerroraboutastackmemoryoverflow,increasetheJVMandrunthetransformationagain.SeeIncreasingJavamemoryallocation.
Parenttopic:Errormessagesandtroubleshooting
LogfilesWhenyouruntheDITA-OT,keyinformationisloggedonthescreen.Thisinformationalsoiswrittentoalogfile.Ifyouencounteraproblem,youcananalyzethisinformationtodeterminethesourceoftheproblemandthentakeactiontoresolveit.
TheloggingbehaviorvariesdependingonwhetheryouusetheDITA-OTcommand-linetoolorAnttoinvokeatoolkitbuild.
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 ParametersAnt -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.
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:Eclipsecontent,Eclipsehelp,HTMLHelp,JavaHelp,TocJS,andXHTML.
Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.
Antparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.
Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.
Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.
Antparameters:LegacyPDFtransformationCertainparametersarespecifictothelegacyPDFtransformation.
Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.
Antparameters:Other
Antparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.
Antparameters:XHTMLtransformationCertainparametersarespecifictotheXHTMLtransformation.
Parenttopic:Reference
RelatedconceptsAnt
RelatedtasksPublishingDITAcontentfromAnt
Antparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.
Table1.Antparameters:AlltransformationsParameters Description
args.debugSpecifieswhetherdebugginginformationisincludedinthelog.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:ThisparameterisnotavailableforthePDFtransformation.
args.filterSpecifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.Filterfilesmusthavea.ditavalor.DITAVALextension.
args.grammar.cache
Specifieswhetherthegrammar-cachingfeatureoftheXMLparserisused.Theallowedvaluesareyesandno;thedefaultvalueisno.
Note:Thisoptiondramaticallyspeedsupprocessingtime.However,thereisaknown
problemwithusingthisfeaturefordocumentsthatuseXMLentities.Ifyourbuildfailswithparsererrorsaboutentityresolution,setthisparametertono.
args.input
Specifiesthemasterfileforyourdocumentationproject.TypicallythisisaDITAmap,howeveritalsocanbeaDITAtopicifyouwanttotransformasingleDITAfile.Thepathcanbeabsolute,relativetoargs.input.dir,orrelativetothedirectorywhereyourproject'santbuildscriptresidesifargs.input.dirisnotdefined.
args.input.dirSpecifiesthebasedirectoryforyourdocumentationproject.Thedefaultvalueistheparentdirectoryofthefilespecifiedbyargs.input.
args.logdir SpecifiesthelocationwheretheDITA-OTplaceslogfilesforyourproject.
args.tablelink.style
Specifieshowcrossreferencestotablesarestyled.SpecifyingNUMBERresultsin"Table5";specifyingTITLEresultsinthetitleofthetable.CorrespondstotheXSLTparameterTABLELINK.
Note:ThisparameterisnotavailableforthePDFtransformation.
clean.tempSpecifieswhethertheDITA-OTdeletesthefilesinthetemporarydirectoryafteritfinishesabuild.Theallowedvaluesareyesandno;thedefaultvalueisyes.
dita.dir SpecifieswheretheDITA-OTisinstalled.
dita.extSpecifiesanextensiontouseforDITAtopics;AllDITAtopicswillusethissingleextensioninthetempdirectory.Thedefaultvalueis.xml.CorrespondstoXSLTparameterDITAEXT.
dita.extname
SpecifiesthefileextensionthattheDITA-OTusesforfilesinthetemporarydirectory.Theallowedvaluesarexmlanddita;thedefaultvalueisxml.
Note:Thisparameterisdeprecatedinfavorofthedita.extparameter.
dita.temp.dirSpecifiesthelocationofthetemporarydirectory.ThetemporarydirectoryiswheretheDITA-OTwritestemporaryfilesthataregeneratedduringthetransformationprocess.
dita.input.valfile
Specifiesafilterfiletobeusedtoinclude,exclude,orflagcontent.Filterfilesmusthavea.ditavalor.DITAVALextension.
Note:Deprecatedinfavoroftheargs.filterparameter.
generate.copy.outer
SpecifieswhethertogenerateoutputfilesforcontentthatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:
1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory..
2–GenerateoutputforthecontentthatislocatedoutsidetheDITAmapdirectory.
3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.
Seegenerate.outer.copyparameterformoreinformation.
SpecifieshowtheDITAOThandlescontentfilesthatarelocatedinorbelowthedirectorycontainingthemasterDITAmap.Thefollowingvaluesaresupported:
fail–Failquicklyiffilesaregoingtobegeneratedorcopiedoutsideofthedirectory
outer.control
warn(default)–Completetheoperationiffileswillbegeneratedorcopiedoutsideofthedirectory,butlogawarning
quiet–Quietlyfinishwithonlythosefiles;donotgeneratewarningsorerrors.
Thegen-list-without-flaggingAnttaskgeneratesaharmlesswarningforcontentthatislocatedoutsidethemapdirectory;youcansuppressthesewarningsbysettingthepropertytoquiet.
Warning:MicrosoftHTMLHelpCompilercannotproduceHTMLHelpfordocumentationprojectsthatuseoutercontent.ThecontentfilesmustresideinorbelowthedirectorycontainingthemasterDITAmapfile,andthemapfilecannotspecify".."atthestartofthe@hrefattributesfor<topicref>elements.
output.dirSpecifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.
transtype
Specifiestheoutputformat.Youcancreateplug-instoaddnewvaluesforthisparameter;bydefault,thefollowingvaluesareavailable:
docbook
eclipsehelp
eclipsecontent
htmlhelp
javahelp
legacypdf
odt
wordrtf
troff
xhtml
validateSpecifieswhethertheDITA-OTvalidatesthecontent.Theallowedvaluesaretrueandfalse;thedefaultvalueistrue.
Parenttopic:Antparameters
Antparameters:CommonHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsecontent,Eclipsehelp,HTMLHelp,JavaHelp,TocJS,andXHTML.
Table1.Antparameters:HTML-basedtransformationsParameters Description
args.artlblSpecifieswhethertogeneratealabelforeachimage;thelabelwillcontaintheimagefilename.Theallowedvaluesareyesandno;thedefaultvalueisno.
args.breadcrumbsSpecifieswhethertogeneratebreadcrumblinks.Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstotheXSLTparameterBREADCRUMBS.
args.copycss Specifieswhethertocopythecustom.cssfiletotheoutputdirectory.
args.css Specifiesthenameofacustom.cssfile.
args.csspathSpecifiesthelocationofacopied.cssfilerelativetotheoutputdirectory.CorrespondstoXSLTparameterCSSPATH.
args.cssrootSpecifiesthedirectorythatcontainsthecustom.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.rellinks
Specifieswhichlinkstoincludeintheoutput.Thefollowingvaluesaresupported:
none–Nolinksareincluded.
all–Alllinksareincluded.
nofamily–Parent,child,next,andprevious
linksarenotincluded.
Defaultvaluedependsonthetransformationtype.
args.indexshowSpecifieswhetherthecontentof<indexterm>elementsarerenderedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.
args.outextSpecifiesthefileextensionforHTMLorXHTMLoutput.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.xslSpecifiesacustomXSLfiletobeusedinsteadofthedefaultXSLtransformation(xsl\dita2xhtml.xsl).Theparametermustspecifyafullyqualifiedfilename.
onlytopic.in.mapSpecifieswhetherfilesthatarelinkedto,orreferencedwitha@conrefattribute,generateoutput.Ifsettoyes,onlyfilesthatarereferenceddirectlyfromthemapwillgenerateoutput.
generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.
Parenttopic:Antparameters
Relatedreference
Antparameters:EclipsecontenttransformationAntparameters:EclipsehelptransformationAntparameters:HTMLHelptransformationAntparameters:JavaHelptransformationAntparameters:XHTMLtransformation
Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.
Table1.Antparameters:EclipsecontenttransformationParameters Descriptionargs.eclipsecontent.tocSpecifiesthenameoftheTOCfile
Parenttopic:Antparameters
RelatedconceptsEclipsecontenttransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.
Table1.Antparameters:EclipsehelptransformationParameters Descriptionargs.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.
Specifiesthesymbolicname(akapluginID)intheoutputforanEclipseHelpproject.The@idvaluefromtheDITAmaportheEclipsemapcollection(Eclipsehelp
args.eclipse.symbolic.namespecialization)isthesymbolicnamefortheplugininEclipse.Thedefaultvalueisorg.sample.help.doc.
Tip:ThetoolkitignoresthevalueofthisparameterwhenitprocessesanEclipsemap.
Parenttopic:Antparameters
RelatedconceptsEclipsehelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.
Table1.Antparameters:HTMLHelptransformationParameters Description
args.htmlhelp.includefileSpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.
Parenttopic:Antparameters
RelatedconceptsHTMLhelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.
Table1.Antparameters:JavaHelptransformationParameters Description
args.javahelp.mapSpecifiesthenameoftheditamapfileforaJavaHelpproject.
args.javahelp.tocSpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.
Parenttopic:Antparameters
RelatedconceptsJavaHelptransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Antparameters:LegacyPDFtransformationCertainparametersarespecifictothelegacyPDFtransformation.
Table1.Antparameters:LegacyPDFtransformationParameters Description
args.fo.output.rel.links
Specifieswhethertorenderrelatedlinksintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheargs.fo.include.rellinksparameterisspecified,thisparameterisignored.
args.fo.userconfig SpecifiestheuserconfigurationfileforFOP.
Parenttopic:Antparameters
RelatedconceptsLegacyPDFtransformation
RelatedreferenceAntparameters:Alltransformations
Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.
Table1.Antparameters:ODTtransformationParameters Description
args.odt.img.embedDetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.
Parenttopic:Antparameters
RelatedconceptsODTtransformation
RelatedreferenceAntparameters:Alltransformations
Antparameters:OtherTable1.Antparameters:Other
Parameter Descriptiondita.preprocess.reloadstylesheet SpecifieswhethertheDITA-OT
reloadstheXSLstylesheetsthatareusedforthetransformation.Theallowedvaluesaretruefalse;thedefaultvalueisfalse
Tip:Settheparametertotrueyouwanttousemorethanonesetofstylesheetstoprocessacollectionoftopics.TheparameteralsoisusefulforlargeprojectsthatgenerateJavaout-of-memoryerrorsduringtransformation.Alternatively,youcanadjustthesizeofyourJavamemoryheapifsettingdita.preprocess.reloadstylesheet
forthisreason.
dita.preprocess.reloadstylesheet.conrefdita.preprocess.reloadstylesheet.maprefdita.preprocess.reloadstylesheet.mappulldita.preprocess.reloadstylesheet.maplink
dita.preprocess.reloadstylesheet.topicpull
Parenttopic:Antparameters
Antparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.
Table1.Antparameters:PDFtransformationParameters Description
args.bookmap-orderSpecifiesifthefrontmatterandbackmattercontentorderisretainedinbookmap.Theallowedvaluesareretainanddiscard;thedefaultvalueisdiscard
args.fo.userconfig SpecifiestheuserconfigurationfileforFOP.
args.gen.task.lblSpecifieswhethertogenerateheadingsforsectionswithintasktopics.TheallowedvaluesareYESNO;thedefaultvalueisNO.CorrespondstotheXSLTparameterGENERATE-TASK-LABELS.
args.rellinks
Specifieswhichlinkstoincludeintheoutput.Thefollowingvaluesaresupported:
none–Nolinksareincluded.
all–Alllinksareincluded.
nofamily–Parent,child,next,andpreviouslinksarenotincluded.
Defaultvaluedependsonthetransformationtype.
args.xsl.pdfSpecifiesanXSLfilethatisusedtooverridethedefaultXSLtransformation(plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xslYoumustspecifythefullyqualifiedfilename.
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-tempissettofalse,thisparameterisignored.
Parenttopic:Antparameters
RelatedconceptsPDFtransformation
RelatedreferenceAntparameters:Alltransformations
Antparameters:XHTMLtransformationCertainparametersarespecifictotheXHTMLtransformation.
Table1.Antparameters:XHTMLtransformationParameters Description
args.xhtml.contenttargetSpecifiesthevalueofthe@targetattributeonthe<base>elementintheTOCfile.Thedefaultvalueiscontentwin.
args.xhtml.toc SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.
args.xhtml.toc.classSpecifiesthevalueofthe@classattributeonthe<body>elementintheTOCfile.Foundinmap2htmltoc.xsl.
Parenttopic:Antparameters
RelatedconceptsXHTMLtransformation
RelatedreferenceAntparameters:AlltransformationsAntparameters:CommonHTML-basedtransformations
Command-linetoolparametersCertainparametersapplytoallDITA-OTtransformations.OtherparametersarecommontotheHTML-basedtransformations.Finally,someparametersapplyonlytothespecifictransformationtypes.
Youmustsupplytheparameterstothecommand-linetoolusingthefollowingsyntax:
/parameter:value
Command-linetoolparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.
Command-linetoolparameters:AllHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsecontent,Eclipsehelp,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:XHTMLtransformationCertainparametersarespecifictotheXHTMLtransformation.
Parenttopic:Reference
RelatedconceptsCommand-linetool
RelatedtasksPublishingDITAcontentfromthecommand-linetool
Command-linetoolparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.
Table1.Command-linetoolparameters:AlltransformationsParameters Description
basedir
Thedirectorywhereyourproject'santbuildscriptresides.TheDITA-OTwilllookforyour.ditafilesrelativetothisdirectory.DITA-OT'sdefaultbuildscriptsetsthisasanattributeoftheproject,butyoucanalsodefineitasaprojectproperty.
cleantempSpecifieswhethertheDITA-OTdeletesthefilesinthetemporarydirectoryafteritfinishesabuild.Theallowedvaluesareyesandno;thedefaultvalueisyes.
debugSpecifieswhetherdebugginginformationisincludedinthelog.Theallowedvaluesareyesandno;thedefaultvalueisno.
ditadir SpecifieswheretheDITA-OTisinstalled.
ditaext
SpecifiesthefileextensionthattheDITA-OTusesforfilesinthetemporarydirectory.Theallowedvaluesarexmlanddita;thedefaultvalueisxml.
Note:Thisparameterisdeprecatedinfavorofthedita.extparameter.
ditalocale
Specifiesthelanguagelocalefiletouseforsortingindexentries.
Note:ThisparameterisnotavailablefortheXHTMLtransformation.
Specifieswhetherthecontentof<draft-comment>and<required-cleanup>elementsisincludedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.CorrespondstoXSLTparameter
draft DRAFTinmostXSLTmodules.
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.
outdirSpecifiesthenameandlocationoftheoutputdirectory.Bydefault,theoutputiswrittentoDITA-dir\out.
outextSpecifiesanextensiontouseforDITAtopics;AllDITAtopicswillusethissingleextensioninthetempdirectory.Thedefaultvalueis.xml.CorrespondstoXSLTparameterDITAEXT.
tempdirSpecifiesthelocationofthetemporarydirectory.ThetemporarydirectoryiswheretheDITA-OTwritestemporaryfilesthataregeneratedduringthetransformationprocess.
transtype
Specifiestheoutputformat.Youcancreateplug-instoaddnewvaluesforthisparameter;bydefault,thefollowingvaluesareavailable:
docbook
eclipsehelp
eclipsecontent
htmlhelp
javahelp
legacypdf
odt
wordrtf
troff
xhtml
validateSpecifieswhethertheDITA-OTvalidatesthecontent.Theallowedvaluesaretrueandfalse;thedefaultvalueistrue.
Parenttopic:Command-linetoolparameters
Command-linetoolparameters:AllHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes:Eclipsecontent,Eclipsehelp,HTMLHelp,JavaHelp,TocJS,andXHTML.
Note:Youmustspecifyanabsolutepathasthevalueforthefollowingparameters:
ftr
hdr
hdf
Table1.Command-linetoolparameters:AllHTML-basedtransformationsParameters Descriptionargs.css Specifiesthenameofacustom.cssfile.
artlblSpecifieswhethertogeneratealabelforeachimage;thelabelwillcontaintheimagefilename.Theallowedvaluesareyesandno;thedefaultvalueisno.
copycss Specifieswhethertocopythecustom.cssfiletotheoutputdirectory.
csspathSpecifiesthelocationofacopied.cssfilerelativetotheoutputdirectory.CorrespondstoXSLTparameterCSSPATH.
cssroot Specifiesthedirectorythatcontainsthecustom.cssfile.DITA-OTwillcopythefilefromthislocation.
ftr
SpecifiesanXMLfilethatcontainscontentforarunningfooter.CorrespondstoXSLTparameterFTR.
Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.
Specifieswhethertogenerateoutputfilesforcontent
generateouter
thatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:
1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory..
2–GenerateoutputforthecontentthatislocatedoutsidetheDITAmapdirectory.
3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.
Seegenerate.outer.copyparameterformoreinformation.
hdf SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.
hdr
SpecifiesanXMLfilethatcontainscontentforarunningheader.CorrespondstotheXSLTparameterHDR.
Note:TheXMLfilemustcontainvalidXML.Acommonpracticeistoplaceallcontentintoa<div>element.
indexshowSpecifieswhetherthecontentof<indexterm>elementsarerenderedintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.
onlytopicinmapSpecifieswhetherfilesthatarelinkedto,orreferencedwitha@conrefattribute,generateoutput.Ifsettoyes,onlyfilesthatarereferenceddirectlyfromthemapwillgenerateoutput.SpecifieshowtheDITAOThandlescontentfilesthatarelocatedinorbelowthedirectorycontainingthemasterDITAmap.Thefollowingvaluesaresupported:
fail–Failquicklyiffilesaregoingtobegeneratedorcopiedoutsideofthedirectory
outercontrol
warn(default)–Completetheoperationiffileswillbegeneratedorcopiedoutsideofthedirectory,butlogawarning
quiet–Quietlyfinishwithonlythosefiles;donotgeneratewarningsorerrors.
Thegen-list-without-flaggingAnttaskgeneratesaharmlesswarningforcontentthatislocatedoutsidethemapdirectory;youcansuppressthesewarningsbysettingthepropertytoquiet.
Warning:MicrosoftHTMLHelpCompilercannotproduceHTMLHelpfordocumentationprojectsthatuseoutercontent.ThecontentfilesmustresideinorbelowthedirectorycontainingthemasterDITAmapfile,andthemapfilecannotspecify".."atthestartofthe@hrefattributesfor<topicref>elements.
usetasklabelsSpecifieswhethertogenerateheadingsforsectionswithintasktopics.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).Theparametermustspecifyafullyqualifiedfile
name.
Parenttopic:Command-linetoolparameters
RelatedreferenceCommand-linetoolparameters:EclipsecontenttransformationCommand-linetoolparameters:EclipsehelptransformationCommand-linetoolparameters:HTMLhelptransformationCommand-linetoolparameters:JavaHelptransformationCommand-linetoolparameters:XHTMLtransformation
Command-linetoolparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.
Table1.Command-linetoolparameters:EclipsecontenttransformationParameters DescriptioneclipsecontenttocSpecifiesthenameoftheTOCfile
Parenttopic:Command-linetoolparameters
RelatedconceptsEclipsecontenttransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.
Table1.Command-linetoolparameters:EclipsehelptransformationParameters Descriptioneclipsehelptoc 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.
Table1.Command-linetoolparameters:HTMLhelptransformationParameters Description
htmlhelpincludefileSpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.
Parenttopic:Command-linetoolparameters
RelatedconceptsHTMLhelptransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.
Table1.Command-linetoolparameters:JavaHelptransformationParameters Description
javahelpmap SpecifiesthenameoftheditamapfileforaJavaHelpproject.
javahelptocSpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.
Parenttopic:Command-linetoolparameters
RelatedconceptsJavaHelptransformation
RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations
Command-linetoolparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.
Table1.Command-linetoolparameters:ODTtransformationParameters Description
odtimgembed DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.
Parenttopic:Command-linetoolparameters
RelatedconceptsODTtransformation
RelatedreferenceCommand-linetoolparameters:Alltransformations
Command-linetoolparameters:PDFtransformationCertainparametersarespecifictothePDF2transformation.
Table1.Command-linetoolparameters:PDFtransformationParameters Description
fooutputrellinksSpecifieswhethertorenderrelatedlinksintheoutput.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheargs.fo.include.rellinksparameterisspecified,thisparameterisignored.
fouserconfig SpecifiestheuserconfigurationfileforFOP.
retaintopicfo
SpecifieswhethertoretainthegeneratedFOfile.Theallowedvaluesareyesandno;thedefaultvalueisno.Iftheconfigurationpropertyorg.dita.pdf2.use-out-tempissettofalse,thisparameterisignored.
xslpdfSpecifiesanXSLfilethatisusedtooverridethedefaultXSLtransformation(plugins\org.dita.pdf2\xsl\fo\topic2fo_shell.xsl).Youmustspecifythefullyqualifiedfilename.
Parenttopic:Command-linetoolparameters
RelatedconceptsPDFtransformation
RelatedreferenceCommand-linetoolparameters:Alltransformations
Command-linetoolparameters:XHTMLtransformationCertainparametersarespecifictotheXHTMLtransformation.
Table1.Command-linetoolparameters:XTMLtransformationParameters Description
xhtmltoc SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.
Parenttopic:Command-linetoolparameters
RelatedconceptsXHTMLtransformation
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.
processing-mode
SpecifieshowtheDITA-OThandleserrorsanderrorrecovery.Thefollowingvaluesareallowed:
strict—Whenanerrorisencountered,theDITA-OTstopsprocessing.
lax(default)—Whenanerroris
encountered,theDITA-OTattemptstorecoverfromit.
skip—Whenanerrorisencountered,theDITAcontinuesprocessingbutdoesnotattempterrorrecovery.
org.dita.pdf2.index.frame-markup
(PDFtransformationonly)SpecifieshowtheDITA-OThandleslegacyFrameMakersyntaxfor<indexterm>elements.Thefollowingvaluesareallowed:
true—EnablesspecialprocessingoflegacyFrameMakersyntaxfor<indexterm>elements.StandardDITA<indexterm>elementsareprocessedalso.
false(default)—DisablesspecialprocessingoflegacyFrameMakersyntaxfor<indexterm>elements.
Note:Settingtheorg.dita.pdf2.index.frame-markupparametertoyesonlyaffectshowindexentriesaregeneratedinPDFoutput.Forexample,an<indexterm>files:topic</index>elementwillgenerateanindexentryof"files:topic"inaCHMfile.
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
DITAOpenToolkitDeveloperReferenceTheDITAOpenToolkitDeveloperReferenceisdesignedtoprovidemoreadvancedinformationabouttheDITAOT.ItisgearedtoanaudiencethatneedsinformationabouttheDITA-OTarchitecture,configuringandextendingtheDITA-OT,andcreatingDITA-OTplug-ins.
ArchitectureoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISspecificationfortheDarwinInformationTypingArchitecture(DITA).ThetoolkitusesANT,XSLT,andJavatoimplementtransformingDITAcontent(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.
CustomizingPDFoutputExampleofPDFoutputcustomizationwithacustomtransformation
type.
InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.
Implementationdependentfeatures
Extendedfunctionality
ArchitectureoftheDITAOpenToolkitTheDITAOpenToolkit(DITA-OT)isanopen-sourceimplementationoftheOASISspecificationfortheDarwinInformationTypingArchitecture(DITA).ThetoolkitusesANT,XSLT,andJavatoimplementtransformingDITAcontent(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.
XHTMLprocessingmodulesTheDITA-OTshipswithseveralvarietiesofXHTMLoutput,eachofwhichfollowsroughlythesamepaththroughtheprocessingpipeline.AllXHTML-basedtransformationbeginwiththesamecalltothepre-processingmodule,afterwhichtheygenerateXHTMLfilesandthenbranchtocreatethetransformation-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.
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.ThisstepisimplementedinAntandJava.
2. Debugandfilter(debug-filter)Thedebug-filterstepprocessesallreferencedDITAcontentandcreatescopiesinatemporarydirectory.AstheDITAcontentiscopied,filteringisperformed,debugginginformationisinserted,andtablecolumnnamesareadjusted.ThisstepisimplementedinJava.
3. Copyrelatedfiles(copy-files)Thecopy-filesstepcopiesnon-DITAresourcestotheoutputdirectory,suchasHTMLfilesthatarereferencedinamaporimagesthatarereferencedbyaDITAVALfile.
4. Conrefpush(conrefpush)Theconrefpushstepresolves"conrefpush"references.Thissteponlyprocessesdocumentsthatuseconrefpushorthatareupdatedduetothepushaction.ThisstepisimplementedinJava.
5. Conref(conref)Theconrefstepresolvesconrefattributes,processingonlytheDITAmapsortopicsthatusethe@conrefattribute.ThisstepisimplementedinXSLT.
6. Movemetadata(move-meta-entries)
Themove-meta-entriessteppushesmetadatabackandforthbetweenmapsandtopics.Forexample,indexentriesandcopyrightsinthemaparepushedintoaffectedtopics,sothatthetopicscanbeprocessedlaterinisolationwhileretainingallrelevantmetadata.ThisstepisimplementedinJava.
7. Resolvekeyref(keyref)ThekeyrefstepexaminesallthekeysthataredefinedintheDITAsourceandresolvedthekeyreferences.Linksthatmakeuseofkeysareupdatedsothatany@hrefvalueisreplacedbytheappropriatetarget;key-basedtextreplacementisalsoperformed.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.ThisstepisimplementedinAntandJava.
Theresultofthislistisasetofseverallistfilesinthetemporarydirectory,includingdita.listanddita.xml.properties.
Listfileproperty Listfile Listpropertycanditopicsfile canditopics.list canditopicslistchunkedditamapfile chunkedditamap.list chunkedditamaplistchunkedtopicfile chunkedtopic.list chunkedtopiclist
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
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:Conrefpush(conrefpush)
Conrefpush(conrefpush)Theconrefpushstepresolves"conrefpush"references.Thissteponlyprocessesdocumentsthatuseconrefpushorthatareupdatedduetothepushaction.ThisstepisimplementedinJava.
Parenttopic:Pre-processingmodulesPrevioustopic:Copyrelatedfiles(copy-files)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:Resolvekeyref(keyref)
Resolvekeyref(keyref)ThekeyrefstepexaminesallthekeysthataredefinedintheDITAsourceandresolvedthekeyreferences.Linksthatmakeuseofkeysareupdatedsothatany@hrefvalueisreplacedbytheappropriatetarget;key-basedtextreplacementisalsoperformed.ThisstepisimplementedinJava.
Parenttopic:Pre-processingmodulesPrevioustopic:Movemetadata(move-meta-entries)Nexttopic:Resolvecodereferences(codref)
Resolvecodereferences(codref)Thecoderefstepresolvesreferencesmadewiththe<coderef>element.ThisstepisimplementedinJava.
The<coderef>isusedtoreferencecodestoredexternallyinnon-XMLdocuments.Duringthepre-processingstep,thereferencedcontentispulledintothecontaining<codeblock>element.
Parenttopic:Pre-processingmodulesPrevioustopic:Resolvekeyref(keyref)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>element
willbecreatedasthelastchildoftheflaggedelement:
<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
XHTMLprocessingmodulesTheDITA-OTshipswithseveralvarietiesofXHTMLoutput,eachofwhichfollowsroughlythesamepaththroughtheprocessingpipeline.AllXHTML-basedtransformationbeginwiththesamecalltothepre-processingmodule,afterwhichtheygenerateXHTMLfilesandthenbranchtocreatethetransformation-specificnavigationfiles.
CommonXHTMLprocessingAfterthepre-processingoperationruns,XHTML-basedbuildseachrunacommonseriesofAnttargetstogenerateXHTMLfile.Navigationmaybecreatedbeforeorafterthissetofcommonroutines.
DefaultXHTMLprocessingAftertheXHTMLfilesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythexhtmltransformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.
EclipsehelpprocessingTheeclipsehelptransformationgeneratesXHTML-basedoutputandfilesthatareneedingtocreateanEclipseHelpsystemplug-in.OncethenormalXHTMLprocesshasrun,thedita.map.eclipsetargetisusedtocreateasetofcontrolfilesandnavigationfiles.
TocJSprocessingThetocjstransformationwasoriginallycreatedasaplug-inthatdistributedoutsideofthetoolkit,butitnowshipsbundledinthedefaultpackages.ThisXHTML-basedoutputtypecreatesaJavaScriptbasedframesetwithTOCentriesthatexpandandcollapse.
HTMLHelpprocessingThehtmlhelptransformationcreatedHTMLHelpcontrolfiles.IfthebuildrunsonasystemthathastheHTMLHelpcompilerinstalled,thecontrolfilesarecompiledintoaCHMfile.
JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.
Parenttopic:ArchitectureoftheDITAOpenToolkit
CommonXHTMLprocessingAfterthepre-processingoperationruns,XHTML-basedbuildseachrunacommonseriesofAnttargetstogenerateXHTMLfile.Navigationmaybecreatedbeforeorafterthissetofcommonroutines.
Afterthepre-processingiscompleted,thefollowingtargetsarerunforalloftheXHTML-basedbuilds:
Ifthearg.cssparameterispassedtothebuildtoaddaCSSfile,thecopy-csstargetcopiestheCSSfilefromitssourcelocationtotherelativelocationintheoutputdirectory.
IfaDITAVALfileisused,thecopy-revflagtargetcopiesthedefaultstart-andend-revisionflagsintotheoutputdirectory.
TheDITAtopicsareconvertedtoXHTMLfiles.Unlessthe@chunkattributewasspecified,eachDITAtopicinthetemporarydirectorynowcorrespondstooneXHTMLfile.Thedita.inner.topics.xhtmltargetisusedtoprocessdocumentsthatareinthemapdirectory(orsubdirectoriesofthemapdirectory).Thedita.outer.topics.xhtmltargetisusedtoprocessdocumentsthatareoutsideofthescopeofthemap,andthusmightendupoutsideofthedesignatedoutputdirectory.VariousDITA-OTparameterscontrolhowdocumentsprocessedbythedita.outer.topics.xhtmltargetarehandled.
Parenttopic:XHTMLprocessingmodules
DefaultXHTMLprocessingAftertheXHTMLfilesaregeneratedbythecommonroutine,thedita.map.xhtmltargetiscalledbythexhtmltransformation.ThistargetgeneratesaTOCfilecalledindex.html,whichcanbeloadedintoaframeset.
Parenttopic:XHTMLprocessingmodules
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:XHTMLprocessingmodules
TocJSprocessingThetocjstransformationwasoriginallycreatedasaplug-inthatdistributedoutsideofthetoolkit,butitnowshipsbundledinthedefaultpackages.ThisXHTML-basedoutputtypecreatesaJavaScriptbasedframesetwithTOCentriesthatexpandandcollapse.
ThefollowingAnttargetscontrolmostoftheTocJSprocessing:
tocjsInit
Setsupdefaultproperties.ThistargetdetectswhetherbuildshavealreadyspecifiedanameforJavaScriptcontrolfile;ifnot,thedefaultnametoctree.jsisused.
map2tocjs
Callsthedita.map.tocjstarget,whichgeneratesthecontentsframeforTocJSoutput.
tocjsDefaultOutput
EnsuresthattheXHTMLprocessingmoduleisrun.Ifscriptsaremissingrequiredinformation,suchasanameforthedefaultframeset,thistargetcopiesdefaultstyleandcontrolfiles.ThistargetwasaddtotheDITA-OTinversion1.5.4;earlierversionsoftheTocJStransformationcreatedonlytheJavaScriptcontrolfilebydefault.
Parenttopic:XHTMLprocessingmodules
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:XHTMLprocessingmodules
JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.
TherearetwoprimaryAnttargets:
dita.map.javahelp
CreatesallofthefilesthatareneededtocompileJavaHelp,includingatableofcontents,sortedindex,andhelpmapfile.
compile.Java.Help
SearchesforaJavaHelpcompileronthesystem.Ifacompilerisfound,thehelpprojectiscompiled.
Parenttopic:XHTMLprocessingmodules
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.xmlinthetemporaryprocessingdirectory.
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.
Installingplug-insPlug-insaregenerallydistributedaszipfiles.Therearetwostepstoinstallingaplug-in:unzippingandintegrating.
Removingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.
RebuildingtheDITA-OTdocumentationTheDITA-OTshipswithAntscriptsthatenableyoutorebuildthetoolkitdocumentation.Thisisespeciallyhelpfulifyourenvironmentcontainsplug-insthatintegrateadditionalmessagesintothetoolkit.
Parenttopic:DITAOpenToolkitDeveloperReference
Installingplug-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
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(XHTML,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).
dita.xsl.fo
Overridethe(nowdeprecated)originalPDFoutput,whichisstillavailablewiththetransformtype"legacypdf".
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
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>
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:importelementsbasedonXSLTimportextensionpoint.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
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
Procedure
1. Createanewplug-indirectorycom.example.print-pdfintoDITA-OTpluginsdirectory.
2. Createaplug-inconfigurationfileplugin.xml,declarethenewtransformationtypeprint-pdfanddependencies.
<?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. AddanAntscriptintegrator.xmltodefinethetransformationtype.
<?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. Addacfg/catalog.xmlfiletotakecustomXSLTstylesheetsintouse.
<?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. Addattributeandvariableoverridestocfg/fo/attrs/custom.xsl
<?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. AddXSLToverridestocfg/fo/xsl/custom.xsl
<?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. Addvariabledefinitionfilecfg/common/vars/en.xmlforEnglishtooverridegeneratedtext.
<?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
Theplug-indirectoryshouldhavethelayoutandfiles:
com.example.print-pdf/
cfg/
common/
vars/
en.xml
fo/
attrs/
custom.xsl
xsl/
custom.xsl
catalog.xml
integrator.xml
plugin.xml
Whattodonext
Runintegrationprocesstoinstalltheplug-inandtaketheprint-pdftransformationtypeintouse.
Parenttopic:DITAOpenToolkitDeveloperReference
InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.
include.rellinks
Spaceseparatedlistoflinkrolestobeoutput;valuetoken#defaultdenotesdefaultrolevalue.Propertydefaultvaluedependsontransformationtype.Definedbyargs.rellinks,butmaybeoverriddendirectly.
Parenttopic:DITAOpenToolkitDeveloperReference
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
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.
DITAOpenToolkitProjectManagementGuidelinesTheDITAOpenToolkitProjectManagementGuidelinesaredesignedtoprovideinformationabouthowtheprojectismanaged.TheseguidelinesaregearedtoanaudiencethatneedsinformationabouthowtoparticipateinthedevelopmentoftheDITA-OT.
Theprojectismanagedsimilarlytocommercialsoftware-developmentprojects;itusesrequirementsgathering,planvalidationwithstakeholdersandcontributors,scheduledactivities,tests,reviews,andbuilds.Qualityisstronglyemphasized.
GoalsandobjectivesoftheDITAOpenToolkitThegoaloftheDITAOpenToolkit(DITA-OT)istoprovideahigh-qualityimplementationforproduction-leveloutputofDITAcontent,builtinaprofessionally-managedprojectenvironmentbyvettedcontributors,andtestedthoroughlyforeachrelease.
DITAOpenToolkitdevelopmentprocessTheDITAOpenToolkit(DITA-OT)developmentprocessismodeledafterdevelopmentprocessesforotherpopularandsuccessfulopen-sourceprojects,mostnotablyEclipse.
HowtoparticipateintheDITAOpenToolkitAnyindividualoranyorganizationcancontributetotheproject;contributionsmustadheretotheexistingtoolkitlicense(s)andshouldfitinwiththegeneralgoalsoftheproject.Allmajorcontributorswillgetappropriaterecognitioninreleaseannouncementsandontheprojecthomepage.
GoalsandobjectivesoftheDITAOpenToolkitThegoaloftheDITAOpenToolkit(DITA-OT)istoprovideahigh-qualityimplementationforproduction-leveloutputofDITAcontent,builtinaprofessionally-managedprojectenvironmentbyvettedcontributors,andtestedthoroughlyforeachrelease.
TheDITA-OTisdesignedtomeettheneedsofuserswhowanttopublishDITAcontent,fromindividualusersrunningthetoolkitinastand-alonemodetovendorswhoincorporatethetoolkitintotheirsoftwareproducts.Thedifferentdistributionpackagesaredesignedtomeettheneedsofthesedifferentaudiences.
TheDITA-OTprojectkeepsuptodatewiththelatestDTDandSchemaupdatesfromtheOASISDITATechnicalCommittee(TC),whichdevelopsandmaintainstheDITAstandard.AstheDITATCproducesdraftsoffutureversions,theDITA-OTworkstocreateearlysupportfornewfeaturesandhelpstotestthenewdraftversionsofthestandard.
Theprojectagreeswiththeopen-sourcemottoof"Releaseearlyandoften"andseekstodevelopwideconsensusonissues.
Parenttopic:DITAOpenToolkitProjectManagementGuidelines
RelatedconceptsDistributionpackages
DITAOpenToolkitdevelopmentprocessTheDITAOpenToolkit(DITA-OT)developmentprocessismodeledafterdevelopmentprocessesforotherpopularandsuccessfulopen-sourceprojects,mostnotablyEclipse.
Version1.0wasreleasedFebruary27,2005.Version2.0wasreleasedJune29,2012.
ProjectrolesandresponsibilitiesTheDITAOpenToolkit(DITA-OT)projecthasthefollowingroles:Projectmanager,committer,andcontributor.Eachrolehasdifferentrightsandobligations.
DITAOpenToolkitreleasemanagementTheDITA-OTprojectworkswithanagiledevelopmentprocess;itreleasestest(milestone)buildsapproximatelyeverymonth,anditencouragesfeedbackonthetestbuildswhilefunctionisbeingdeveloped.Stablereleasesaretypicallyissuedapproximatelyeverysixmonths.
FeaturerequestsanddefectreportsFeaturerequestsanddefectreportscanbesubmittedatanytimethroughtheprojectpageatGitHub.
Parenttopic:DITAOpenToolkitProjectManagementGuidelines
ProjectrolesandresponsibilitiesTheDITAOpenToolkit(DITA-OT)projecthasthefollowingroles:Projectmanager,committer,andcontributor.Eachrolehasdifferentrightsandobligations.
Projectmanager(PM)
Theprojectmanagerisresponsibleformanagingtheproject.ThePMprovidesleadershiptoguidetheoveralldirectionoftheprojectandremovesobstacles,solvesproblems,andresolvesconflicts.ThePMworkstoensurethatthefollowinggoalsaremet:
Theprojectoperateseffectively.
Allprojectplans,technicaldocuments,andreportsarepubliclyavailable.
Theprojectoperatesusingtheopen-sourcerulesofengagement,whichstressmeritocracy,transparency,andopenparticipation.
Committer
Committersoverseethequalityandoriginalityofallcontributions.Committersinfluencesthedevelopmentoftheprojectandhavewriteaccesstothesource-coderepository.Thispositionreflectsatrackrecordofhigh-qualitycontributionstotheproject.
Contributor
Contributorscontributecode,documentation,fixes,tests,orotherworktotheproject.Contributorsdonothavewriteaccesstothesource-coderepository.Thereisnolimittothescopeofsuchcontributions,thoughcontributorswhoexpecttodonatealargeamountofnewfunctiontotheprojectareencouragedtoworkwithcommittersinadvance.
Parenttopic:DITAOpenToolkitdevelopmentprocess
DITAOpenToolkitreleasemanagementTheDITA-OTprojectworkswithanagiledevelopmentprocess;itreleasestest(milestone)buildsapproximatelyeverymonth,anditencouragesfeedbackonthetestbuildswhilefunctionisbeingdeveloped.Stablereleasesaretypicallyissuedapproximatelyeverysixmonths.
Eachiterationbeginswithameetingofprojectcontributors.ThemeetingminutesarestoredontheprojectWikiandareavailabletothepublic.Activecontributorsaredirectlyinvitedtothesemeetings,butanybodyinterestedintheDITA-OTdevelopmentiswelcometoattend.Ifyouareinterestedinattendingthesemeetings,jointhedita-ot-developermailinglistandsendanotetothelistorlistowners.
Eachiterationkick-offmeetingcoversthefollowingtopics:
Issuesfromthepreviousiteration
Plansfromeachcontributorfortheupcomingiterationorfornewworkthatwillspanmultipleiterations
Designdiscussionforanysignificantplannedfeaturesorfixes
Longer-termplansforcontributionstothecurrentorfollowingrelease
(Asneeded)Otherprojectissuesorhottopics,suchaschangestothetestandbuildprocess,interestfromnewcontributors,etc.
Thekick-offmeetingforthefinaliterationbeforeastablebuildcoversthefollowingtopics:
Evaluationofwhatisallowedintheiteration;thefinaliterationtypicallyhasnomajorchangesinordertoassurequalityinthestablebuild.
Assessmentofwhetherallreleasenotesandotherartifactsareup-to-dateandreadyforafinalbuild.
Whenaniterationiscomplete,thebuildisuploadedtoSourceForge.TestbuildsareplacedintheLatestTestBuildfolder.Attheendofareleasecycle,thebuildsareloadedtotheStableReleasefolder,andtheprojectinformationisupdatedtoreflectthelatestrelease.
Parenttopic:DITAOpenToolkitdevelopmentprocess
Relatedinformationhttps://lists.sourceforge.net/lists/listinfo/dita-ot-developerhttps://github.com/dita-ot/dita-ot/wiki/Meeting-minutes
FeaturerequestsanddefectreportsFeaturerequestsanddefectreportscanbesubmittedatanytimethroughtheprojectpageatGitHub.
Thecoreprojectcontributorstrackandaddressbugsreportedagainsttheproject;theyissuepatchesbasedonurgency.Thecorecontributorsalsowillprovidefeedbackonrequestsfornewfeaturesordesignchanges,buttheymightnotbeabletoprovidedevelopmentassistance.
Allnewbugreportsorfeaturerequestsshouldbesubmittedthroughgithub:DITA-OTbugandfeaturetracker.
Featurerequests
Theprojectcommittersperiodicallyreviewnewfeaturerequestswithcontributorsandinterestedparties;whenpossible,theymakeplanstoimplementthenewfeatures.
Ifanexistingprojectcontributorisinterestedinanewrequest,theitemisassignedtothecontributorandimplementedbasedonthecontributor'sschedule.Otherwise,iftherequestisvalidandinlinewithprojectgoals,itisleftopenforaninterestedpartytopickupandimplement.Somerequestsarebestimplementedasaplug-inratherthaninthecoreDITA-OTcode;inthosecases,projectcommitterssuggestalternativesandclosetherequest.
Defectreports
Theprojectcommittersdeterminetheowneroftherelevantcomponentsandassignthedefecttothecomponentownerforvalidationanddisposition.Responses,fixes,andworkaroundsareissuedfasterifthedefectreportincludessamplefilesandclearinstructionsforreproducingtheissue.
IfbugsarefoundintheOASISDITADTDsorSchemas,theyarefixedinthetoolkitandreportedtotheOASISDITATechnicalCommittee.
Parenttopic:DITAOpenToolkitdevelopmentprocess
Relatedinformationhttps://github.com/dita-ot/dita-ot/issuesDITA-OTBugandFeaturetrackeratGitHub
HowtoparticipateintheDITAOpenToolkitAnyindividualoranyorganizationcancontributetotheproject;contributionsmustadheretotheexistingtoolkitlicense(s)andshouldfitinwiththegeneralgoalsoftheproject.Allmajorcontributorswillgetappropriaterecognitioninreleaseannouncementsandontheprojecthomepage.
Contributorscansubmitnewfeatures,patches,andbugfixesusingexistinggithubfacilities(thisisdonebycreatinga"pullrequest"withingithub).TheCommitter(s)whoownstherelevantcomponentswillfirstdoduediligencetocheckcodeoriginalityandlicensingaccordingtotheDITAOpenToolkitContributionPolicy.Afterduediligence,theCommitter(s)willusehis/herownjudgmentonwhethertoacceptthecodeintotheoriginalcodebase,requestupdatestothecode,orsuggestthatthecodebemaintainedasanexternalpatchorplug-in.
Contributionsarealwaysencouraged,andgenerallyfallintooneoftwogroups,asdeterminedbyprojectCommitters:
Bugfixesandminorpatchesareacceptedwithlittleoverhead.
Majorcontributionsrequirethecontributortosignaformstatingthatthesubmitterisfreetocommitthecode(individuallyoronbehalfofanemployer),andthatthecodecomplieswiththecurrenttoolkitlicenseterms.
Duediligenceforsubmissionofbugfixesandpatchesfromnon-committersAnyorganizationorindividualmaysubmitbugfixesusingagithub"pullrequest",generallytiedtoaspecificreportintheproject'sissuetracker.
DITAOpenToolkitContributionPolicyThepurposeoftheDITAOpenToolkitContributionPolicyistosetforththegeneralprinciplesunderwhichtheDITAOpenToolkitprojectshallacceptcontributions,licensecontributions,licensematerialsownedbythisproject,andmanageotherintellectual
propertymatters.
DITA-OTContributionQuestionnaireForm1.2
Parenttopic:DITAOpenToolkitProjectManagementGuidelines
RelatedinformationDITA-OTBugandFeaturetrackeratGitHubSignupfortoolkitdevelopermailinglistHelpwithgettingstartedatGitHub
Duediligenceforsubmissionofbugfixesandpatchesfromnon-committersAnyorganizationorindividualmaysubmitbugfixesusingagithub"pullrequest",generallytiedtoaspecificreportintheproject'sissuetracker.
Beforecommittingcodefromabugfixorpatchprovidedbyathirdpartywhohasnotsignedacurrentcontributionformfortheproject,Committersshouldaskthefollowingquestionsandfollowupasappropriateinordertoensurethatthecodecanbecontributedtotheproject:
Whatisyournameandwhoisyouremployer?
DidyouwritethecodethatyouwishtocontributetotheDITAOpenToolkitproject?(Ifthecontributorsaysno,thecodeshouldnotbecomea“Contribution”totheproject.Thecontributormaybeaskedtoidentifythecompletedetailsofthecode’ssourceandofanylicensesorrestrictionsapplicabletothecode,buttheworkshouldbeconspicuouslymarkedas“Submittedonbehalfofathird-party:[nameofcontributor]”.)
DoyouhavetherighttograntthecopyrightandpatentlicensesforthecontributionthataresetforthintheCPLversion1.0licenseandApacheLicenseversion2.0?
Doesyouremployerhaveanyrightstocodethatyouhavewritten,forexample,throughyourcontractforemployment?Ifso,hasyouremployergivenyoupermissiontocontributethecodeonitsbehalforwaiveditsrightsinthecode?
Areyouawareofanythird-partylicensesorotherrestrictions(suchasrelatedpatentsortrademarks)thatcouldapplytoyourcontribution?Ifso,whatarethey?
Parenttopic:HowtoparticipateintheDITAOpenToolkit
DITAOpenToolkitContributionPolicyThepurposeoftheDITAOpenToolkitContributionPolicyistosetforththegeneralprinciplesunderwhichtheDITAOpenToolkitprojectshallacceptcontributions,licensecontributions,licensematerialsownedbythisproject,andmanageotherintellectualpropertymatters.
Overview
TheCommonPublicLicense(CPL)andApacheLicense2.0,whichareincorporatedhereinbyreference,willserveastheprimarylicensesunderwhichtheCommitterwillacceptcontributionsofsoftware,documentation,information(including,butnotlimitedto,ideas,concepts,know-howandtechniques)and/orothermaterials(collectively"Content")totheprojectfromContributors.AcopyoftheCPLandApacheLicense2.0canbefoundattherootdirectoryoftheDITAOpenToolkitdeliverablepackage.
ThisContributionPolicyshouldatalltimesbeinterpretedinamannerthatisconsistentwiththePurposesofthethisprojectassetforthintheDITAOpenToolkitDevelopmentProcessgoalsandobjectives.ThisContributionPolicyshallserveasthebasisforhownon-Committersinteractwiththisprojectthroughparticipationinthisproject,web-sitesowned,controlled,publishedand/ormanagedundertheauspicesofthethisproject,orotherwise.
TheCommonPublicLicenseandApacheLicense2.0shallserveastheprimarylicensesunderwhichtheCommitter(s)shallacceptsoftware,documentation,information(including,butnotlimitedto,ideas,concepts,know-howandtechniques)and/orothermaterials(collectively"Content")fromcontributorsincluding,butnotlimitedto,ContributorsandCommitters.
TheDITAOpenToolkitprojectprovidesaprocessforacceptingbugfixesandcontributionsfrompartieswhohavenotacceptedthelicensetobeContributors.SeeDueDiligenceforSubmissionofBugFixesandPatchesfromNon-Committers
DUEDILIGENCEANDRECORDKEEPING
TheCommitter(s),shallberesponsibleforscrutinizingallContentcontributedtotheDITAOpenToolkitprojectandhelpensurethattheContributionPolicylicensingrequirementssetforthabovearemet.Exceptassetforthbelow,theapplicableCommittershallconductthefollowingactivitiespriortouploadinganyContentintotherepositoryorotherwisemakingtheContentavailablefordistribution:
1. ContactthepotentialcontributoroftheContentthroughanappropriatechannelofcommunicationandcollect/confirmthefollowing:
Contributor'sname,currentaddress,phonenumberande-mailaddress;
Nameandcontactinformationofthecontributor'scurrentemployer,ifany;
Ifthecontributorisnotself-employed,theCommittermustrequestandreceiveasignedconsentform(tobeprovidedbytheCommitter)fromthecontributor'semployerconfirmingthattheemployerdoesnotobjecttotheemployeecontributingtheContent.
DetermineiftheContentcanbecontributedunderthetermsoftheCPLandApacheLicense2.0orthealternativetermsandconditionssuppliedbytheContributor.Thiscanbedonebyaskingthecontributorquestionssuchas;
1. DidyoudevelopalloftheContentfromscratch;
2. Ifnot,whatmaterialsdidyouusetodeveloptheContent?
3. Didyoureferenceanyconfidentialinformationofanythirdparty?
4. Ifyoureferencedthirdpartymaterials,underwhattermsdid
youreceivesuchmaterials?
IfitisdeterminedbytheCommitterthattheContentisnottheoriginalworkoftheContributor,collectthecontactinformationofthecopyrightholderoftheoriginalorunderlyingwork.ThecopyrightholderoftheContentortheunderlyingworkmaythenneedtobecontactedtocollectadditionalinformation.
2. TheContributor(s)shalldocumentallinformationrequestedin(1)aboveandfillinContributionQuestionnaire(tobeprovidedbytheCommitter)andprovidethecompletedContributionQuestionnairetotheCommitter.
3. TheCommittershallalsoberesponsibleforrunningascantooltohelpensurethattheContentdoesnotincludeanycodenotidentifiedbythecontributor.
4. Basedontheinformationcollected,theCommittershallusehis/herreasonablejudgmenttodetermineiftheContentcanbecontributedundertermsandconditionsthatareconsistentwiththelicensingrequirementsofthisIPPolicy.
IftheapplicableCommitterhasanydoubtsabouttheabilitytodistributetheContentundertermsandconditionsthatareconsistentwiththeCPLandApacheLicense2.0ortheproposedalternativetermsandconditions,theCommittermaynotuploadthecodetotherepositoryorotherwisedistributetheContent.TheCommitter(s)shallberesponsibleforfiling/maintainingtheinformationcollectedforfuturereferenceasneeded.
Theaboverecordkeepingrequirementsshallnotapplyto
MinormodificationstoContentpreviouslycontributedtoandacceptedbytheCommitter(s).
ArticlesandWhitePapers
InformationorminorContentmodificationsprovidedthroughbugreports,mailinglistsandnewsgroups
Whiletherecordkeepingrequirementsdonotapplytotheitemslistedabove,CommittersmustconductreasonableduediligencetosatisfythemselvesthatproposedContributionscanbelicensedunderthetermsoftheCPLandApacheLicense2.0.
Parenttopic:HowtoparticipateintheDITAOpenToolkit
DITA-OTContributionQuestionnaireForm1.2TheContributionQuestionnaireisthefirststepininitiatingtheduediligenceandapprovalprocessbytheProjectManager(PM)foranysignificantcontributionofcontenttobecommittedtotheproject.PriortocompletingthisQuestionnaire,theCommittershouldhavetechnicalagreementfromthePMthatthenewcodeisrequired.OncethePMhasapproved,theCommitter,withtheassistanceofoneormoreofthecontributors,maybegintheduediligenceandapprovalprocessbycompletingandsubmittingthisquestionnaire.
Whatismeantbyasignificantcontribution?
Anyinitialcodecontributionusedtokickoffanewproject.Bydefinition,thiscodehasbeenwrittenelsewhereanditneedstobereviewed.
or
Anycontributionauthoredbysomeoneotherthanacommitterwhichisaddingnewfunctionalitytothecodebase.Inmostcases,bugfixesdonotaddnewfunctionalityalthoughit'snotimpossible.
or
Anycontributioncontainingthird-partycodemaintainedbyanotheropensourceproject,individual,group,ororganization.Inadditiontoreviewingthecontribution,ifthelicenseisnottheCommonPublicLicense(CPL)orApacheLicense2.0,thePMwillneedtoreviewandapprovethethird-partylicenseforcompatibilitywiththeCPLorApacheLicense2.0.
HowtosendPMthisform?
Pleasefillinthisformandsignyournameandgetyouremployer'sauthorizedsignature,suchasyourmanager's.thensendascannedcopytoProjectManagerRobertDAnderson.Thescannedcopymaybesenttordandersonatusers.sourceforge.net.
NOTE:Aquestionnaireandapprovalisnotrequiredforbugfixesorminorenhancements.Ifyouhaveanyquestions,pleasesendanemailtotheProjectManager.
YourInfo
Pleaseprovideyourcontactdetails:
Name: Organization: Address: PhoneNumber: E-mail:
Committer
Pleaseprovidecontactdetailsforthecommitterwhowillbeincorporatingthiscontributionintothecodebase.Ifthisisthesameasabove,justput"same"intheNamefield.
Name: Organization: Address: PhoneNumber: E-mail:
PMApproval
PMApprovalisrequiredforallsignificantcontributions.PleaseprovidethecontactinfoofthePMwhohasgivenapprovalforthiscontribution:
Name: PhoneNumber: E-mail:
Contribution
Pleaseprovidedetailsaboutthecontribution:
Component/Module(ifknown):
ContributionName: ContributionVersion:
ContributionSize(inlinesofcode):
ContributionDescription:
Doesthiscontributionrequireanypackagesmaintainedbya3rdparty?
Pleaselistallpkgsrequiredbythecontributionwhicharemaintainedbya3rdparty:(Pleaselistonepackageperlinee.g3rdpartypackagenamev1.0)
SupportingInformation:
DoyouagreetodistributetheContributionunderCommonPublicLicense1.0?
DoyouagreetodistributetheContributionunderApacheLicense2.0?
Provideanyadditionalinformationyoumayhaveregardingintellectualpropertyrights(patents,trademarks,etc.)relatedtotheContribution.Ifthereismorethanonecommitterwhoworkedonthiscontribution,pleaselisttheirnameandemailaddresses.
Contributor
Note:AllofthecontributorsshouldensurethattheypossessthenecessaryrightstomakethecontributionunderthetermsandconditionssetoutintheContributionPolicy.
Pleaseprovidecontactdetailsforthecontributorortheprimarycontributorifthereismorethanone:
Name: Organization: PhoneNumber: E-mail: %ofcontentauthoredinthecontribution:
Ifthereareothercontributors,pleaseprovidenames,organizations,e-mail,andpercentageofcontentauthoredinthecontribution:
Other
Contributors:
Cryptography
Ifthecontributiondealsinanywaywithcryptography,pleaseprovidedetails:
Details: IdentifytheCryptographyalgorithmused:
Contributor'ssignature
Name(TypeorPrint)
Title Signature Date
Contributoremployer'ssignature
Name(TypeorPrint)
Title Signature Date
Parenttopic:HowtoparticipateintheDITAOpenToolkit
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
Background
Thisisanissueinthefollowingsituations:
TheDITAmapisinadirectorythatisapeertodirectoriesthatcontainreferencedobjects.
TheDITAmapisinadirectorythatisbelowthedirectoriesthatcontainthereferencedobjects.
Let'sassumethatthedirectorystructurefortheDITAcontentlookslikethefollowing:
maps
topics
images
TheDITAmapisinthemapsdirectory,thetopicsareinthetopicsdirectory,andtheimagesareintheimagesdirectory.
Settingthegenerate.outer.copyparameterto1
Let'sassumethatyouruntheXHTMLtransformationandspecifyanoutputdirectoryofC:\A-test.Bydefault,TheDITA-OTusesthegenerate.outer.copyparameterwithavalueof1.Outputisnotbuiltforthetopics.Youreceiveonlythefollowingoutput:
A-test
---dita.list
---dita.xml.properties
---index.html
---commonltr.css
---commonrtl.css
Theindex.htmlfilecontainsthenavigationstructure,butallthelinksarebroken,sincenoXHTMLfileswerebuiltforthetopics.
Howdoyoufixthis?Byspecifyingavalueof2or3forthegenerate.outer.copyparameter.
Settingthegenerate.outer.copyparameterto2
Let'sassumethatyouruntheXHTMLtransformationagainandspecifythefollowingparameters:
Thegenerate.outer.copyparameterissetto2.
Theoutput.dirparameterissettoC:\A-test.
Thisiswhatyouroutputlookslike:
C:\A-test
---dita.list
---dita.xml.properties
---index.html
---commonltr.css
---commonrtl.css
...
C:\images
...
C:\topics
Thelinksintheoutputallworkproperly.However,dependingonhowmanyotherdirectoriesarelocatedatthesamelevelofyourbuildsystemastheoutputdirectory,itmightnotbeeasygatheralltheoutputtogetherifyouneedtocopyitelsewhere.
Settingthegenerate.outer.copyparameterto3
Nowyouroutputdirectorystructurelookslikethis:
C:\A-test
---images\
---maps\
---topics\
Theindex.htmlfileisinthemapsdirectory,andtheCSSandotherfilesarelocatedintheoutputdirectory,C:\A-test.Copyingtheoutputdirectoryissimplified.
Parenttopic:Antparameters:CommonHTML-basedtransformations
DITAtoJavaHelpThe"javahelp"transformtypewillgenerateJavaHelpoutput,alongwiththecontrolfilesneededtocompiletheproject.
TheJavaHelpoutputproducesHTMLfilesratherthanXHTMLfiles.InadditiontotheHTMLoutputandCSSfiles,thistransformtypewillreturnthefollowingfiles:
TableofContents(toc.xml)
Sortedindex(mapname_index.xml)
OtherJavaHelpprojectfiles(map.jhmandmapname_helpset.hs)
IftheJavaHelpcompilerislocatedonthesystem,acompiledJavaHelpprojectwillbereturned.
RelatedreferenceAntparameters:JavaHelptransformationCommand-linetoolparameters:JavaHelptransformation
Top Related