DITA Open Toolkit 1.8 - documentation.helpThe DITA Open Toolkit (DITA-OT) is an open-source...

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

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

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

Toolkitdocumentation

Therearetwoprimarysourcesfordocumentationaboutthetoolkit.

Stabledocumentationabouttoolkitusage,parameters,andprojectmanagementcanbefoundonthispage,usingthenavigationpanelontheleft.

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

RelatedconceptsDistributionpackages

RelatedinformationMainDITA-OTpageatdita.xml.orgProjectNewsforDITAOpenToolkit

ShortcutstoimportantinformationDITA-OTstablereleaseDITA-OTlatestdevelopmentbuild

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

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

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

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

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

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

2. RunningthedemobuildAfteryouinstallthefull-easy-installpackage,runthedemobuildtoseethetypeofoutputthatisproducedbytheDITAOpenToolkit.

3. BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.

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

Beforeyoubegin

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

BuildingyourowncontentusingthedemobuildYoucanusethedemobuildtogenerateoutputforyourownDITAcontent.

Procedure

1. Ifnecessary,runthestartcmdfilethatisapplicableforyouroperatingsystem.Youdonotneedtorunthestartcmdfileifyoualreadyhaveacommand-promptorterminalwindowthatwasinvokedbythestartcmdfileopen.

2. FromtheDITA-OTshell,enterthefollowingcommand:

ant-fbuild_demo.xml

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

4. Whenprompted,typethenameoftheoutputdirectory.

5. Whenprompted,typethevalueforthetransformationtype.

Ouputformat ValueDocbook docbookEclipsehelp eclipseHTMLhelp htmlhelpPDF pdfXHTML webXHTMLwithaJavaScriptframeset tocjs

6. Whenprompted,pressEntertostartthetransformation.

Results

TheDITA-OTgeneratesoutputforthespecifiedDITAcontent.Itrunsthetransformationthatyouspecified,andwritestheoutputtothedirectorythatyouspecified.

Whattodonext

ExploreinvokingtheDITA-OTfromeitherAntorthecommand-linetool.Thisenablesyoutospecifyawiderarrayofparametersthanthosesupportedbythedemobuild.

UsingAntorthecommand-linetool,youcanperformthefollowingtasks(andmore):

AddacustomCSSfiletothetransformation

Generatelabelsforthesectionsoftasktopics

Specifythatdraftcommentsareincludedintheoutput

Turnon"Relatedlink"sectionsinaPDFfile

Parenttopic:GettingStartedwiththeDITAOpenToolkitPrevioustopic:Runningthedemobuild

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

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

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

PublishingDITAcontentYoucanuseeitherAntorthecommand-linetooltotransformDITAcontenttothevariousoutputformatsthataresupportedbytheDITAOpenToolkit(DITA-OT).

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

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


DITAOpenToolkitRelease1.8Parenttopic:OverviewoftheDITAOpenToolkit

GeneralEnhancementsandChanges

Preprocessing

Additionalvalidationhasbeenaddedtochecke.g.elementIDuniqueness,andxml:langandURIsyntax.

PDF

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.

PDF

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)

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

#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

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

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

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

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

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

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

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

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.


InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.


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:




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



ApacheFOP,version1.0

ICUforJava,version49.1


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

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

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

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.

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

http://ant.apache.org/

http://saxon.sourceforge.net/

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


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

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

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

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.


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

InstallingtheminimalorstandardpackageonLinuxorMacOSXIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

Beforeyoubegin

Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:


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

PDF

TocJS

TROFF

XHTML


InstallingtheminimalorstandardpackageonWindowsIfyoualreadyhavelocally-installedcopiesofAntandtheotherrequiredtools,installeithertheminimalorstandardpackage.

Beforeyoubegin

Ensurethatyouhavethefollowingprerequisitesoftwareinstalled:


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

PDF

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.


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.


RelatedreferenceAntparameters:EclipsecontenttransformationCommand-linetoolparameters:Eclipsecontenttransformation

DITAtoEclipsehelpTheeclipsehelptransformationgeneratesXHTMLoutput,CSSfiles,andthecontrolfilesthatareneededforEclipsehelp.

InadditiontotheXHTMLoutputandCSSfiles,thistransformationreturnsthefollowingfiles,wheremapnameisthenameofthemasterDITAmap.

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


RelatedreferenceAntparameters:EclipsehelptransformationCommand-linetoolparameters:Eclipsehelptransformation

RelatedinformationOfficialEclipseWebsite

http://eclipse.org

DITAtoHTMLHelp(CHM)ThehtmlhelptransformationgeneratesHTMLoutput,CSSfiles,andthecontrolfilesthatareneededtoproduceaMicrosoftHTMLHelpfile.

InadditiontotheHTMLoutputandCSSfiles,thistransformationreturnsthefollowingfiles,wheremapnameisthenameofthemasterDITAmap.

Filename Descriptionmapname.hhc Tableofcontentsmapname.hhk Sortedindexmapname.hhp HTMLHelpprojectfile

mapname.chm

CompiledHTMLHelp

Note:ThisfileisgeneratedonlyiftheHTMLHelpWorkshopisinstalledonthebuildsystem.


RelatedreferenceAntparameters:HTMLHelptransformationCommand-linetoolparameters:HTMLhelptransformation

DITAtolegacyPDFtransformationThelegacypdftransformationproducesaPDFusingthedemoPDFbuild.Thistransformationisdeprecated.

ThefirstversionsofthetoolkitcamewiththedemoPDFbuild,whichwasreplacedbythemorerobustPDFplug-in(alsoknownasPDF2)inrelease1.4.3.ThedemoPDFbuildisnolongermaintainedbytheDITA-OTdevelopers,althoughthetoolkitincludesitinordertosupportoldercustomizationsandbuildscriptsthatextendedthecode.


RelatedreferenceAntparameters:LegacyPDFtransformation

DITAtoOpenDocumentTypeTheodttransformationproducesoutputfilesthatusetheOpenDocumentformat,whichisusedbytoolssuchasOpenOffice.

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


RelatedreferenceAntparameters:ODTtransformationCommand-linetoolparameters:ODTtransformation

DITAtoPDF(PDF2)Thepdf(orpdf2)transformationgeneratesPDFoutput.

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


RelatedreferenceAntparameters:PDFtransformationCommand-linetoolparameters:PDFtransformation

DITAtoRichTextFormatThewordrtftransformationproducesanRTFfileforusebyMicrosoftWord.

ThestructureofthegeneratedRTFfileisthesameasthenavigationstructureintheDITAmap.Toavoidlosingfilesinthefinaloutput,makesuretheDITAmapcontainsalltopicsthatarereferencedfromanyindividualtopics.

Thewordrtftransformationhasthefollowinglimitations:

Flagging,filtering,andrevisionbarsarenotsupported.

Styleattributesfortablesarenotsupported.

Tableswithinlistitemsarenotsupported.

OutputstylessupportedbyotherDITA-OTtransformations,forexample,XandY,arenotsupported.


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

ThetocjstransformationwasupdatedsothatitproducesXHTMLoutputandusesadefaultframeset.Thistransformationalsowasaddedtothebuild_demo.xmlscriptasatransformation-typeoption.


DITAtoTroffThetrofftransformationproducesoutputforusewiththeTroffvieweronUnix-styleplatforms,particularlyforprogramssuchastheManpageviewer.

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


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

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

ToruntheXHTMLtransformation,setthetranstypeparametertoxhtml.Ifyouarerunningthedemobuild,specifywebratherthanxhtml.


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


RelatedconceptsAnt

RelatedreferenceAntparameters

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

TheDITA-OTusesAnttomanagetheXSLTscriptsthatareusedtoperformthevarioustransformation;italsousesAnttomanageintermediatestepsthatarewritteninJava.

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

Parenttopic:PublishingDITAcontentfromAnt

RelatedtasksBuildingoutputusingAntCreatinganAntbuildscriptPublishingDITAcontentfromAnt

RelatedreferenceAntparametersApacheAntdocumentation

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

BuildingoutputusingAntYoucanbuildoutputbyrunningtheantcommandandspecifyingtheDITA-OTparametersatthecommandprompt.YoualsocanuseanAntbuildscripttoprovidetheDITA-OTparameters

Procedure


2. ToprovidetheDITA-OTparametersfromthecommandprompt,issuethefollowingcommand:

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

where:

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.


RelatedconceptsAnt

RelatedtasksCreatinganAntbuildscript



CreatinganAntbuildscriptInsteadoftypingtheDITA-OTparametersatthecommandprompt,youmightwanttocreateanAntbuildscriptthatcontainsalloftheparameters.

Procedure

1. CreateanXMLfilethatcontainsthefollowingcontent:

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

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

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

<targetname="@target-name@">

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

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

<propertyname="transtype"value="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.


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

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

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

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

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

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

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

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

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

</ant>

</target>

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

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

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

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

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

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

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

</ant>

</target>

</project>

Inadditiontothemandatoryparameters(args.inputandtranstype),thechmandpdftargetseachspecifysomeoptionalparameters:

Theargs.gen.task.lblpropertyissettoYES,whichensuresthatheadingsareautomaticallygeneratedforthesectionsoftasktopics.

Theoutput.dirpropertyspecifieswheretheDITAOTwritestheoutputofthetransformations.

ThepdftargetalsospecifiesthatrelatedlinksshouldbegeneratedinthePDF,butonlythoselinksthatarecreatedbyrelationshiptablesand<link>elements.

Finally,thealltargetsimplyspecifiesthatboththechmandpdftargetshouldberun.

Whattodonext

AnotherresourceforlearningaboutAntscriptsarethefilesinthesamples/ant_samplesdirectory.ThisdirectorycontainstheAntbuildfilesusedbythedemobuild,aswellastemplatesthatyoucanusetocreateAntscripts.


RelatedconceptsAnt

RelatedtasksBuildingoutputusingAnt



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

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

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


RelatedconceptsCommand-linetool

RelatedreferenceCommand-linetoolparameters

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

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

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

Parenttopic:PublishingDITAcontentfromthecommand-linetool

RelatedtasksBuildingoutputusingthecommand-linetoolPublishingDITAcontentfromthecommand-linetool


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

Procedure


2. Fromthecommandprompt,issuethefollowingcommand:

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

where:

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



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.


RelatedreferenceLocalizationoverviewintheOASISDITAstandard

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

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

Generatedtext

GeneratedtextistextthatisrenderedautomaticallyintheoutputthatisgeneratedbytheDITA-OT;thistextisnotlocatedintheDITAsourcefiles.Thefollowingareexamplesofgeneratedtext:

Theword"ChapterinaPDFfile.

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

Indexsorting

TheDITA-OTcanuseonlyasinglelanguagetosortindexes.

Bi-directionaltext

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

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

Parenttopic:GlobalizingDITAcontent

Supportedlanguages:HTML-basedtransformationsTheDITAOpenToolkit(DITA-OT)supportsover50languagesandlanguagevariantsfortheHTML-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


RelatedreferenceHowtoaddsupportfornewlanguagesinXHTML

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

Table1.Supportedlanguages:PDFtransformation

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


ErrormessagesandtroubleshootingThissectioncontainsinformationaboutproblemsthatyoumightencounterandhowtoresolvethem.

DITA-OTerrormessagesTheerrormessagesgeneratedbytheDITAOpenToolkitcontainamessageID,severityinformation,andmessagetext.Thistopiclistseacherrormessagegeneratedbythetoolkitandprovidesadditionalinformationthatmightbehelpfulinunderstandingandresolvingtheerrorcondition.

OthererrormessagesInadditiontoerrormessagesgeneratedbytheDITAOpenToolkit,youmightalsoencountererrormessagesgeneratedbyJavaorothertools.

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

Accessinghelpfromthecommand-linetoolYoucanaccessalistofsupportedparametersforthecommand-linetoolbyissuingthe-helpparameter.

DetermingtheversionoftheDITAOpenToolkitYoucanusethecommand-linetooltodeterminetheversionoftheDITAOT.

EnablingdebugmodeWhenthedebugmodeisenabled,additionaldiagnosticinformationiswrittentothelogfile.Thisinformation,whichincludesenvironmentvariablesandstacktracedata,canhelpyoudeterminetherootcauseofaproblem.

IncreasingJavamemoryallocation

Ifyouareworkingwithlargedocumentswithextensivemetadataorkeyreferences,youwillneedtoincreasethememoryallocationfortheJavaprocess.Youcandothisfromthecommand-linepromptforaspecificsession,oryoucanincreasethevalueoftheANT_OPTSenvironmentalvariable.


DITA-OTerrormessagesTheerrormessagesgeneratedbytheDITAOpenToolkitcontainamessageID,severityinformation,andmessagetext.Thistopiclistseacherrormessagegeneratedbythetoolkitandprovidesadditionalinformationthatmightbehelpfulinunderstandingandresolvingtheerrorcondition.

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

Informational(I)

Thetoolkitencounteredaconditionofwhichyoushouldbeaware.Forexample,draftcommentsareenabledandwillberenderedintheoutput.

Warning(W)

Thetoolkitencounteredaproblemthatshouldbecorrected.Processingwillcontinue,buttheoutputmightnotbeasexpected.

Error(E)

Thetoolkitencounteredamoresevereproblem,andtheoutputisaffected.Forexample,somecontentismissingorinvalid,orthecontentisnotrenderedintheoutput

Fatal(F)

Thetoolkitencounteredaseverecondition,processingstopped,andnooutputisgenerated.

MessageID Severity Messagetext Additionaldetails

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


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

ThedomainsattributeisusedinspecializedDITAdocumentstohelpdeterminewhichdomainelementsarelegal.ThismessagewillonlyappearifDITAspecializationwasnotdefinedproperly.


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

AllspecializedDITAelementsmustdefineaclassattributetoprovideancestryinformation.ThismessagewillonlyappearaspecializedDITAelementdidnotdefineaclassattribute.


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

Thisinformationalmessageisintendedtohelpyoucatchfilterconditionsthatmayhavebeenspecifiedimproperly;ifthevalueiscorrect,noactionisneeded.

DOTJ033E ErrorNovalidcontentisfoundintopicref'%1'duringchunkprocessing.Pleasespecifyanexistingandvalidtopicforthetopicref.

DOTJ034F Fatal

Failedtoparsetheinputfile'%1'(thecontentofthefileisnotvalid).Iftheinputfile'%1'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".


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

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


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

DOTJ043W Warning replaceanelementthatdoesnotexist(element"%1"infile"%2").

basedaddressingspecificationfordetailsontheexpectedsyntax.Ifthesyntaxiscorrect,itispossiblethatthetargetwasfilteredoutofyourbuildusingaDITAVALfile.

DOTJ044W Warning

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


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

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

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


Foundanavrefelementthatdoesnotreferenceanything.ThenavrefelementshouldeitherreferenceanotherditamaporanEclipseXMLfile.

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

DOTX005E Error

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

Toremovethismessage,provideanavigationtitleforthereferencedobjectinthemaportopic,orensurethatyouarereferencingavalidlocalDITAtarget.

DOTX006E Error

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

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


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

TheHTMLHelpcompilerwillonlyincludesometypesofinformationinthecompiledCHMfile;thecurrentreferencewillnotbeincluded.

DOTX008E Error File'%1'doesnotexistorcannotbeloaded.

Ensurethatthefileexistsandcanberead.ofthefileinthismessagemayhavebechangedtouseastandardditatopicfileextension('.dita'or'.xml'),insteadoftheoriginalextensionusedbythefile;itmayalsoincludeapathtothetemporarydirectoryratherthantotheoriginal.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.


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.


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.


Thelongdescrefattributeontag'%1'willbeignored.Accessibilityforobjectelementsneedstobehandledanotherway.

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

DOTX039WWarning

Requiredcleanupareafound.Toremovethismessageandhidethecontent,buildyourcontentwithoutusingtheDRAFTparameter.

Thismessageisgeneratedwhencreatingdraftoutputinordertohelpyoulocatealltopicsthatneedtobecleanedup;thecleanupitemswillappearinyouroutputwithstylingthatmakesitstandout.Thecontentwillbehiddenwhen

thedraftparameterisnotactive.


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.


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


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

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

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.


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.


Accessinghelpfromthecommand-linetoolYoucanaccessalistofsupportedparametersforthecommand-linetoolbyissuingthe-helpparameter.

Procedure



java-jarlib/dost.jar-help

Results

Youcanseethebriefdescriptionofthesupportedparametersinthecommand-linewindow.


DetermingtheversionoftheDITAOpenToolkitYoucanusethecommand-linetooltodeterminetheversionoftheDITAOT.

Procedure



java-jarlib/dost.jar-version


EnablingdebugmodeWhenthedebugmodeisenabled,additionaldiagnosticinformationiswrittentothelogfile.Thisinformation,whichincludesenvironmentvariablesandstacktracedata,canhelpyoudeterminetherootcauseofaproblem.

Procedure

Fromthecommandprompt,addthefollowingparameters:

Application ParametersAnt -v-Dargs.debug=yes

Command-linetool/dor-debug

Youalsocanadda<property>elementtoanAnttargetinyourbuildfile,forexample:

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


IncreasingJavamemoryallocationIfyouareworkingwithlargedocumentswithextensivemetadataorkeyreferences,youwillneedtoincreasethememoryallocationfortheJavaprocess.Youcandothisfromthecommand-linepromptforaspecificsession,oryoucanincreasethevalueoftheANT_OPTSenvironmentalvariable.

Procedure

Tochangethevalueforanspecificsession,fromthecommandprompt,issuethefollowingcommand:

Platform CommandWindows setANT_OPTS=%ANT_OPTS%-Xmx1024M

Linux/OSXexportANT_OPTS=$ANT_OPTS-Xmx1024M

ThisincreasestheJVMmemoryallocationto1024megabytes.Theamountofmemorywhichcanbeallocatedislimitedbyavailablesystemmemoryandtheoperatingsystem.

Topersistentlychangethevalue,changethevalueallocatedtotheANT_OPTSenvironmentvariableonyoursystem.IfyouusethestartcmdfilefromtheFullEasyInstalltosetupatoolkitsession,editthatfiletochangethevalue.


ReferenceThissectionisdesignedtohelpuserstolocateinformationeasilyandquickly.ItincludesdocumentationfortheDITAOpenToolkit(DITA-OT)parametersandconfigurationproperties.

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

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

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


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

Antparameters:AlltransformationsCertainparametersapplytoalltransformationsthataresupportedbytheDITAOpenToolkit.

Antparameters:CommonHTML-basedtransformationsCertainparametersapplytoalltheHTML-basedtransformationtypes: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

pdf

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.


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.


Relatedreference

Antparameters:EclipsecontenttransformationAntparameters:EclipsehelptransformationAntparameters:HTMLHelptransformationAntparameters:JavaHelptransformationAntparameters:XHTMLtransformation

Antparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Table1.Antparameters:EclipsecontenttransformationParameters Descriptionargs.eclipsecontent.tocSpecifiesthenameoftheTOCfile


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.


Specifiesthesymbolicname(akapluginID)intheoutputforanEclipseHelpproject.The@idvaluefromtheDITAmaportheEclipsemapcollection(Eclipsehelp

args.eclipse.symbolic.namespecialization)isthesymbolicnamefortheplugininEclipse.Thedefaultvalueisorg.sample.help.doc.



RelatedconceptsEclipsehelptransformation


Antparameters:HTMLHelptransformationCertainparametersarespecifictotheHTMLHelptransformation.

Table1.Antparameters:HTMLHelptransformationParameters Description

args.htmlhelp.includefileSpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.


RelatedconceptsHTMLhelptransformation


Antparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Table1.Antparameters:JavaHelptransformationParameters Description

args.javahelp.mapSpecifiesthenameoftheditamapfileforaJavaHelpproject.

args.javahelp.tocSpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.


RelatedconceptsJavaHelptransformation


Antparameters:LegacyPDFtransformationCertainparametersarespecifictothelegacyPDFtransformation.

Table1.Antparameters:LegacyPDFtransformationParameters Description

args.fo.output.rel.links

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

args.fo.userconfig SpecifiestheuserconfigurationfileforFOP.


RelatedconceptsLegacyPDFtransformation

RelatedreferenceAntparameters:Alltransformations

Antparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Table1.Antparameters:ODTtransformationParameters Description

args.odt.img.embedDetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.


RelatedconceptsODTtransformation


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


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.


RelatedconceptsPDFtransformation


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.


RelatedconceptsXHTMLtransformation


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.



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

pdf

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.


Specifieswhethertogenerateoutputfilesforcontent

generateouter

thatisnotlocatedinorbeneaththedirectorycontainingtheDITAmapfile.Thefollowingvaluesaresupported:

1(default)–DonotgenerateoutputforcontentthatislocatedoutsidetheDITAmapdirectory..

2–GenerateoutputforthecontentthatislocatedoutsidetheDITAmapdirectory.

3–Shifttheoutputdirectorysothatitcontainsalloutputforthepublication.

Seegenerate.outer.copyparameterformoreinformation.

hdf SpecifiesanXMLfilethatcontainscontenttobeplacedinthedocumenthead.

hdr

SpecifiesanXMLfilethatcontainscontentforarunningheader.CorrespondstotheXSLTparameterHDR.


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.


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

Command-linetoolparameters:EclipsecontenttransformationCertainparametersarespecifictotheEclipsecontenttransformation.

Table1.Command-linetoolparameters:EclipsecontenttransformationParameters DescriptioneclipsecontenttocSpecifiesthenameoftheTOCfile


RelatedconceptsEclipsecontenttransformation

RelatedreferenceCommand-linetoolparameters:AlltransformationsCommand-linetoolparameters:AllHTML-basedtransformations

Command-linetoolparameters:EclipsehelptransformationCertainparametersarespecifictotheEclipsehelptransformation.

Table1.Command-linetoolparameters:EclipsehelptransformationParameters Descriptioneclipsehelptoc SpecifiesthenameoftheTOCfile.

provider

SpecifiesthenameofthepersonororganizationthatprovidestheEclipsehelp.ThedefaultvalueisDITA.


version

Specifiestheversionnumbertoincludeintheoutput.Thedefaultvalueis0.0.0.



RelatedconceptsEclipsehelptransformation


Command-linetoolparameters:HTMLhelptransformationCertainparametersarespecifictotheHTMLhelptransformation.

Table1.Command-linetoolparameters:HTMLhelptransformationParameters Description

htmlhelpincludefileSpecifiesthenameofafilethatyouwantincludedintheHTMLHelp.


RelatedconceptsHTMLhelptransformation


Command-linetoolparameters:JavaHelptransformationCertainparametersarespecifictotheJavaHelptransformation.

Table1.Command-linetoolparameters:JavaHelptransformationParameters Description

javahelpmap SpecifiesthenameoftheditamapfileforaJavaHelpproject.

javahelptocSpecifiesthenameofthefilecontainingtheTOCinyourJavaHelpoutput.Defaultvalueisthenameoftheditamapfileforyourproject.


RelatedconceptsJavaHelptransformation


Command-linetoolparameters:ODTtransformationCertainparametersarespecifictotheODTtransformation.

Table1.Command-linetoolparameters:ODTtransformationParameters Description

odtimgembed DetermineswhetherimagesareembeddedasbinaryobjectswithintheODTfile.


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.


RelatedconceptsPDFtransformation

RelatedreferenceCommand-linetoolparameters:Alltransformations

Command-linetoolparameters:XHTMLtransformationCertainparametersarespecifictotheXHTMLtransformation.

Table1.Command-linetoolparameters:XTMLtransformationParameters Description

xhtmltoc SpecifiesthebasenameoftheTOCfile.Thedefaultvalueisindex.


RelatedconceptsXHTMLtransformation


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

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

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.


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.

Parenttopic:ArchitectureoftheDITAOpenToolkit

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

XSLTmodules

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

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

Javamodules

JavamodulesaretypicallyusedwhenXSLTisapoorfit,suchasforprocessesthatmakeuseofstandardJavalibraries(likethoseusedforindexsorting).Javamodulesarealsousedinmanycaseswhereastepinvolvescopyingfiles,suchastheinitialprocesswheresourcefilesareparsedandcopiedtoatemporaryprocessingdirectory.


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

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

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

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

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

Timeissavedbydiscardingunusedcontentasearlyaspossible;allfuturestepscanloadthedocumentwithoutthisextracontent.

Additionaltimeissavedcasebynotevaluatingthe@conrefattribute;infact,documentAdoesnotevenneedtobeparsed.

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

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

referencingnote.Assumethatthe<note>elementsindocumentAisdefinedasfollows:

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

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


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

1. Generatelists(gen-list)Thegen-liststepexaminestheinputfilesandcreateslistsoftopics,images,documentproperties,orothercontent.Theselistsareusedbylaterstepsinthepipeline.Forexample,onelistincludesalltopicsthatmakeuseoftheconrefattribute;onlythosefilesareprocessedduringtheconrefstageofthebuild.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.


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

Parenttopic:Pre-processingmodulesNexttopic:Debugandfilter(debug-filter)

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

ThefollowingmodificationsaremadetotheDITAsource:

IfaDITAVALfileisspecified,theDITAsourceisfilteredaccordingtotheentriesintheDITAVALfile.

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

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

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

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

Parenttopic:Pre-processingmodulesPrevioustopic:Debugandfilter(debug-filter)Nexttopic: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

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

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

ThemaplinkmodulerunsanXSLTprogramthatevaluatesthemap;itplacesallthegeneratedlinksintoasinglefileinthetemporarydirectory.Themove-linksmodulethenrunsaJavaprogramthatpushesthegeneratedlinksintotheapplicabletopics.

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

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

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

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

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

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

EvaluatingtheDITAVALflags

Flaggingisimplementedasareusablemoduleduringthepreprocessstage.IfaDITAVALfileisnotusedwithabuild,thisstepisskippedwithnochangetothefile.

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

<ditaval-startprop>

Whenanyflagisactiveonanelement,a<ditaval-startprop>elementwillbecreatedasthefirstchildoftheflaggedelement:

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

The<ditaval-startprop>elementwillcontainthefollowing:

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

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

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

<ditaval-endprop>

Whenanyflagisactiveonanelement,a<ditaval-endprop>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.


<val>



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



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

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



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

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

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

</prop>



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

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

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

</revprop>

</val>

Contentexample1:addingstyle

Nowassumethefollowingparagraphexistsinatopic.Classattributesareincluded,astheywouldnormallybeinthemiddleofthepreprocessroutine;@xtrfand@xtrcareleftoffforclarity.

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

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

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

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

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

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


</ditaval-startprop>

Simpleuser;includesstylebutnoimages



</ditaval-endprop>

</p>

Contentexample2:conflictingstyles

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

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

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


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


outputclass="background-color:red;">

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




Conflictingstyles(stillnoimages)




</ditaval-endprop>

</p>

Contentexample3:addingimageflags

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

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

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

</ol>

Asabove,the<ditaval-startprop>and<ditaval-endprop>nesttheactivepropertydefinitions,[email protected]<ditaval-startprop>dropstheendingimage,and<ditaval-endprop>dropsthestartingimage.Tomakedocument-orderprocessingmoreconsistent,propertyflagsarealwaysincludedbeforerevisionsin<ditaval-startprop>,andtheorderisreversedfor<ditaval-endprop>.


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


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


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

</prop>


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

</revprop>


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



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

</revprop>


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

</prop>

</ditaval-endprop>

</ol>

Parenttopic:Pre-processingmodules

Previoustopic:

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.


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.


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

Eclipseusemultiplefilestocontroltheplug-inbehavior.Someofthesecontrolfilesaregeneratedbythebuild,whileothersmightbecreatedmanually.ThefollowingAnttargetscontroltheEclipsehelpprocessing:

dita.map.eclipse.init

Setsupvariousdefaultproperties

dita.map.eclipse.toc

CreatestheXMLfilethatdefinesanEclipsetableofcontents

dita.map.eclipse.index

CreatesthesortedXMLfilethatdefinesanEclipseindex

dita.map.eclipse.plugin

Createstheplugin.xmlfilethatcontrolsthebehaviorofanEclipseplug-in

dita.map.eclipse.plugin.properties

CreatesaJavapropertiesfilethatsetspropertiesfortheplug-in,suchasnameandversioninformation

dita.map.eclipse.manifest.file

CreatesaMANIFEST.MFfilethatcontainsadditionalinformationusedbyEclipse

copy-plugin-files

Checksforthepresenceofcertaincontrolfilesinthesource

directory,andcopiesthosefoundtotheoutputdirectory

dita.map.eclipse.fragment.language.init

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

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


TocJSprocessingThetocjstransformationwasoriginallycreatedasaplug-inthatdistributedoutsideofthetoolkit,butitnowshipsbundledinthedefaultpackages.ThisXHTML-basedoutputtypecreatesaJavaScriptbasedframesetwithTOCentriesthatexpandandcollapse.

ThefollowingAnttargetscontrolmostoftheTocJSprocessing:

tocjsInit

Setsupdefaultproperties.ThistargetdetectswhetherbuildshavealreadyspecifiedanameforJavaScriptcontrolfile;ifnot,thedefaultnametoctree.jsisused.

map2tocjs

Callsthedita.map.tocjstarget,whichgeneratesthecontentsframeforTocJSoutput.

tocjsDefaultOutput

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


HTMLHelpprocessingThehtmlhelptransformationcreatedHTMLHelpcontrolfiles.IfthebuildrunsonasystemthathastheHTMLHelpcompilerinstalled,thecontrolfilesarecompiledintoaCHMfile.

Oncethepre-processingandXHTMLprocessesarecompleted,mostoftheHTMLHelpprocessingishandledbythefollowingtargets:

dita.map.htmlhelp

CreatetheHHP,HHC,andHHKfiles.TheHHKfileissortedbasedonthelanguageofthemap.

dita.htmlhelp.convertlang

Ensuresthatthecontentcanbeprocessedcorrectlybythecompiler,andthattheappropriatecodepagesandlanguagesareused.

compile.HTML.Help

AttemptstodetecttheHTMLHelpcompiler.Ifthecompilerisfound,thefullprojectiscompiledintoasingleCHMfile.


JavaHelpprocessingThejavahelptransformationrunsseveraladditionalAnttargetsaftertheXHTMLprocessingiscompletedinordertocreatecontrolfilesfortheJavaHelpoutput.

TherearetwoprimaryAnttargets:

dita.map.javahelp

CreatesallofthefilesthatareneededtocompileJavaHelp,includingatableofcontents,sortedindex,andhelpmapfile.

compile.Java.Help

SearchesforaJavaHelpcompileronthesystem.Ifacompilerisfound,thehelpprojectiscompiled.


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

ThePDFprocessincludesmanyAnttargets.DuringatypicalconversionfrommaptoPDF,thefollowingtargetsaremostsignificant.

map2pdf2

CreatesamergedfilebycallingacommonJavamergemodule.Itthencallsthepublish.map.pdftargettodotheremainderofthework.

publish.map.pdf

Performssomeinitializationandthencallsthetransform.topic2pdftargettodotheremainderofprocessing.

transform.topic2pdf

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

transform.topic2fo

ConvertthemergedfiletoanXSL-FOfile.ThisprocessiscomposedofseveralAnttargets.

Anttarget Description

transform.topic2fo.index

RunsaJavaprocesstosetupindexprocessing,basedonthedocumentlanguage.Thisstepgeneratesthefilestage1.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.


OpenDocumentFormatprocessingmodulesTheodttransformationcreatesabinaryfileusingtheOASISOpenDocumentFormat.

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

dita.map.odt

ConvertsthemapintoamergedXMLfileusingtheJava-basedtopicmergemodule.ThenanXSLTprocessconvertsthemergedfileintothecontent.xmlfile.

dita.map.odt.stylesfile

ReadstheinputDITAmap,andthenusesXSLTtocreateastyles.xmlfileinthetemporarydirectory.

dita.out.odt.manifest.file

Createsthemanifest.xmlfile

Oncethesetargetshaverun,thegeneratedfilesarezippeduptogetherwithotherrequiredfilestocreatetheoutputODTfile.


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

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

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

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

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

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

Removingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.

RebuildingtheDITA-OTdocumentationTheDITA-OTshipswithAntscriptsthatenableyoutorebuildthetoolkitdocumentation.Thisisespeciallyhelpfulifyourenvironmentcontainsplug-insthatintegrateadditionalmessagesintothetoolkit.


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

Parenttopic:ExtendingtheDITAOpenToolkit

Removingplug-insPlug-inscanbeinstalledbyremovingtheplug-inandrunningintegrationprocess.

Procedure

1. Removeplug-ininstallationdirectory.

2. Runintegrationprocess.

ant-fintegrator.xml


RebuildingtheDITA-OTdocumentationTheDITA-OTshipswithAntscriptsthatenableyoutorebuildthetoolkitdocumentation.Thisisespeciallyhelpfulifyourenvironmentcontainsplug-insthatintegrateadditionalmessagesintothetoolkit.

Procedure

1. Changetothedocdirectory.

2. Runthefollowingcommand:

ant-fbuild.xmltarget

Thetargetparameterisoptionalandspecifiesaspecifictransformationtype.Ittakesthefollowingvalues:

build-html

build-htmlhelp

build-pdf

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


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

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


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

Parenttopic:ConfiguringtheDITAOpenToolkit

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

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

Benefitsofextendingthetoolkitthroughplug-insinclude:

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

Allowsoverridesorcustomizationstogrowfromsimpletocomplexovertime,withnoincreasedcomplexitytotheextensionmechanism.

Plug-inscanbemovedfromversiontoversionwithanupgradedtoolkitsimplybyunzippingagain,orbycopyingthedirectoryfromoneinstalltoanother;thereisnoneedtore-integratecodebasedonupdatestothecoreprocessing.

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

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

ExtendingtheXMLCatalogTheXMLCatalogsextensionpointisusedtoupdatetheXMLCatalogsusedtoresolveDTDorSchemadocumenttypes,ortoaddURImappings.ThisisrequiredinordertosupportDITAspecializationsornewDITAdocumenttypeshells.

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

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

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

OverridestyleswithXSLTTheXSLTimportextensionpointsareusedtooverridevariousstepsofXSLTprocessing.Forthis,theextensionattributeindicatesthestepthattheoverrideappliesto;thefileattributeisarelativepathtotheoverridewithinthecurrentplugin.TheplugininstallerwilladdanXSLimportstatementtothedefaultcodesothatyouroverridebecomesapartofthenormalbuild.

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

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

AddingJavalibrariestotheclasspathIfyourAntorXSLTextensionsrequireadditionalJavalibrariesintheclasspath,youcanaddthemtotheglobalDITA-OTclasspathwiththefollowingfeature.

AddingdiagnosticmessagesPlug-inspecificwarninganderrormessagescanbeaddedtothesetofmessagessuppliedbytheDITA-OT.ThesemessagescanthenbeusedbyanyXSLToverride.

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

VersionandsupportinformationThefollowingextensionpointsareusedbyconventiontodefineversionandsupportinfowithinaplug-in.

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

Exampleplugin.xmlfileThefollowingisasampleofaplugin.xmlfile.ThisfileaddssupportforanewsetofspecializedDTDs,andincludesanoverridefortheXHTMLoutputprocessor.


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

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

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

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

The<plugin>elementsupportsthefollowingchildelements:

<feature>definesanextensiontocontributetoadefinedextensionpoint.Thefollowingattributesaresupported:

Attribute Description Requiredextension extensionpointidentifier yes

valuecommaseparatedstringvalueoftheextension

eithervalueorfile

file filepathvalueoftheextension,relativetoplugin.xml

eithervalueorfile

type typeofthevalueattribute no

extension-pointdefinesnewaextensionpointthatcanbeusedbyotherplug-ins.Thefollowingattributesaresupported:

Attribute Description Requiredid extensionpointidentifier yesname extensionpointname no

<require>definesplug-independencies.Thefollowingattributesaresupported:

Attribute Description Required

pluginverticalbarseparatedlistofplug-insthatarerequired yes

importance flagwhetherplug-inisrequiredoroptional no

<template>definesfilesthatshouldbetreatedastemplates.Thefollowingattributesaresupported:

Attribute Description Requiredfile filepathtothetemplate,relativetoplugin.xml yes

<meta>definesmetadata.Thefollowingattributesaresupported:

Attribute Description Requiredtype metadatanameyesvalue metadatavalue yes

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

Parenttopic:CreatingDITA-OTplug-ins

ExtendingtheXMLCatalogTheXMLCatalogsextensionpointisusedtoupdatetheXMLCatalogsusedtoresolveDTDorSchemadocumenttypes,ortoaddURImappings.ThisisrequiredinordertosupportDITAspecializationsornewDITAdocumenttypeshells.

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

dita.specialization.catalog.relative

dita.specialization.catalog

AddsthecontentofthecatalogfiledefinedinfileattributetomainDITA-OTcatalogfile.

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

org.dita.pdf2.catalog.relative

AddsthecontentofthecatalogfiledefinedinfileattributetomainPDFplug-incatalogfile.

Example

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

<pluginid="com.example.catalog">

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

</plugin>


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

dita.conductor.target.relative

dita.conductor.target

AddAntimporttomainAntbuildfile.

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

Example

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

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

Thencreatethefollowingfeature:

<pluginid="com.example.ant">

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

</plugin>

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


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

Thegroupofpreprocessingstepsdefinesextensionpointsbeforeandafterthefullpreprocessingchain.

depend.preprocess.pre

Preprocessingpre-target;extendingthistargetrunsyourAnttargetbeforethefullpreprocessroutinebegins.

depend.preprocess.post

Preprocessingpost-target;extendingthistargetrunsyourAnttargetafterthefullpreprocessroutinecompletes.

Inaddition,thereareextensionpointstoexecuteanAnttargetbeforeindividualpreprocessingsteps.

depend.preprocess.clean-temp.pre

Cleantemppre-target

depend.preprocess.gen-list.pre

Generatelistpre-target

depend.preprocess.debug-filter.pre

Debugandfilterpre-target

depend.preprocess.conrefpush.pre

Contentreferencepushpre-target

depend.preprocess.move-meta-entries.pre

Movemetaentriespre-target

depend.preprocess.conref.pre

Contentreferencepre-target

depend.preprocess.coderef.pre

Codereferencepre-target

depend.preprocess.mapref.pre

Mapreferencepre-target

depend.preprocess.keyref.pre

Resolvekeyreferencepre-target

depend.preprocess.mappull.pre

Mappullpre-target

depend.preprocess.chunk.pre

Chunkingpre-target

depend.preprocess.maplink.pre

Maplinkpre-target

depend.preprocess.move-links.pre

Movelinkspre-target

depend.preprocess.topicpull.pre

Topicpullpre-target

depend.preprocess.copy-files.pre

Copyfilespre-target

depend.preprocess.copy-image.pre

Copyimagespre-target

depend.preprocess.copy-html.pre

CopyHTMLpre-target

depend.preprocess.copy-flag.pre

Copyflagpre-target

depend.preprocess.copy-subsidiary.pre

Copysubsidiarypre-target

depend.preprocess.copy-generated-files.pre

Copygeneratedfilespre-target

Example

Thefollowingfeatureadds"myAntTargetBeforeChunk"Anttargettobeexecutedbeforethechunkstepinpreprocessing.ItassumesthatanAntfiledefiningthattargethasalreadybeenintegrated.

<pluginid="com.example.extendchunk">

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

</plugin>

Whenintegrated,theAnttarget"myAntTargetBeforeChunk"willbeaddedtotheAntdependencylistsothatitalwaysrunsimmediatelybeforetheChunkstep.


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

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

dita.conductor.transtype.check

Addnewvaluetolistofvalidtransformationtypenames.

dita.transtype.print

Declaretranstypeasaprinttype.

Example

Thefollowingfeaturedefinesatransformtypeof"newtext"anddeclaresitasaprinttype;usingthistransformtypewillcausethebuildtolookforatargetdita2newtext,definedinarelatedAntextensionfromthethirdfeature:

<pluginid="com.example.newtext">

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

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

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

</plugin>


OverridestyleswithXSLTTheXSLTimportextensionpointsareusedtooverridevariousstepsofXSLTprocessing.Forthis,theextensionattributeindicatesthestepthattheoverrideappliesto;thefileattributeisarelativepathtotheoverridewithinthecurrentplugin.TheplugininstallerwilladdanXSLimportstatementtothedefaultcodesothatyouroverridebecomesapartofthenormalbuild.

ThefollowingXSLTstepsareavailabletooverrideinthecoretoolkit:

dita.xsl.xhtml

Overridesdefault(X)HTMLoutput(includingHTMLHelpandEclipseHelp).ThereferencedfileisintegrateddirectlyintotheXSLTstepthatgeneratesXHTML.

dita.xsl.xslfo

OverridesdefaultPDFoutput(formerlyknownasPDF2).ThereferencedfileisintegrateddirectlyintotheXSLTstepthatgeneratesXSL-FOforPDF.

dita.xsl.docbook

OverridesdefaultDocBookoutput.

dita.xsl.rtf

OverridesdefaultRTFoutput.

dita.xsl.eclipse.plugin

Overridesthestepthatgeneratesplugin.xmlforEclipse.

dita.xsl.conref

Overridesthepreprocessstepthatresolvesconref.

dita.xsl.topicpull

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

dita.xsl.mapref

Overridesthepreprocessstep"mapref"(thestepthatresolvesreferencestoothermaps).

dita.xsl.mappull

Overridesthepreprocessstep"mappull"(thestepthatupdatesnavtitlesinmapsandcausesattributestocascade).

dita.xsl.maplink

Overridesthepreprocessstep"maplink"(thestepthatgeneratesmap-basedlinks).

dita.xsl.fo

Overridethe(nowdeprecated)originalPDFoutput,whichisstillavailablewiththetransformtype"legacypdf".

Example

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

plugin.xml:


<pluginid="com.example.brandheader">

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

</plugin>

xsl/header.xsl:


<xsl:stylesheetversion="1.0"

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

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

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

alt="ExampleCompanyBanner"/></div>

</xsl:template>

</xsl:stylesheet>


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

Thegeneratedtextextensionpointisusedtoaddnewstringstothedefaultsetofgeneratedtext.Thereareseveralreasonsyoumaywanttousethis:

Itcanbeusedtoaddnewtextforyourownprocessingextensions;forexample,itcouldbeusedtoaddlocalizedversionsofthestring"Userresponse"toaidinrenderingtroubleshootinginformation.

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

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

dita.xsl.strings

Addnewstringstogeneratedtextfile.

Example:addingnewstrings

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



<langlist>

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

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

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

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

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

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

</langlist>

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

<stringsxml:lang="en-us">

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

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

</strings>

Usethefollowingextensioncodetoincludeyourstringsinthesetofgeneratedtext:

<pluginid="com.example.strings">

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

</plugin>

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

<xsl:call-templatename="getString">

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

</xsl:call-template>

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

Example:modifyingexistingstrings

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

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

<stringsxml:lang="en-us">

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

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

</strings>

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

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

Example:addinganewlanguage

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



<langlist>

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

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

</langlist>

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

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

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

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

RelatedreferenceLanguagessupportedbythecoretoolkit

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

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

<dummy>



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

</dummy>

Passthevalueusingthefollowingextensions:

dita.conductor.html.param

PassparameterstoHTMLandHTMLHelpXSLT

dita.conductor.xhtml.param

PassparameterstoXHTMLandEclipseHelpXSLT

dita.conductor.xhtml.toc.param

PassparameterstoXHTMLTOCXSLT

dita.conductor.eclipse.toc.param

PassparameterstoEclipseHelpTOCXSLT

dita.preprocess.conref.param

PassparameterstoconrefXSLT

dita.preprocess.mapref.param

PassparameterstomaprefXSLT

dita.preprocess.mappull.param

PassparameterstomappullXSLT

dita.preprocess.maplink.param

PassparameterstomaplinkXSLT

dita.preprocess.topicpull.param

PassparameterstotopicpullXSLT

dita.conductor.pdf2.param

PassparameterstoPDF2XSLT

Example

Thefollowingplug-inwillpasstheparametersdefinedinsideofinsertParameter.xmlasinputtotheXHTMLprocess.Generally,anadditionalXSLToverridewillmakeuseoftheparametertodosomethingnewwiththegeneratedcontent.

<pluginid="com.example.newparam">

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

</plugin>


AddingJavalibrariestotheclasspathIfyourAntorXSLTextensionsrequireadditionalJavalibrariesintheclasspath,youcanaddthemtotheglobalDITA-OTclasspathwiththefollowingfeature.

dita.conductor.lib.import

AddJavalibrariestoDITA-OTclasspath.

Example

Thefollowingplug-inaddsthecompiledJavacodefrommyJavaLibrary.jarintotheglobalDITA-OTclasspath.XSLTorAntcodecanthenmakeuseoftheaddedcode.

<pluginid="com.example.addjar">

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

</plugin>

NowassumethatinthiscasemyJavaLibrary.jarperformssomevalidationstepinthemiddleofprocessing,andyoualwayswantittorunimmediatelybeforetheconrefstep.Inthatcaseyouneedtomakeuseofseveralfeaturesinthisplug-in

TheJARfilemustbeaddedtotheclasspath.

AnAnttargetmustbecreatedthatusesthisclass,andtheAntwrapperintegratedintothecode.

TheAnttargetmustbeaddedtothedependencychainforconref.

Inthisextendedexample,thefilesmightlooksomethinglikethis.

plugin.xml:


<pluginid="com.example.samplejava">



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



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



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

</plugin>

antWrapper.xmlimportsthenewAntcode:


<dummy>

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

</dummy>

calljava-antcode.xml:

<projectdefault="validateWithJava">

<targetname="validateWithJava">

<javaclassname="com.example.sampleValidation">



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

</java>

</target>

</project>

AddingdiagnosticmessagesPlug-inspecificwarninganderrormessagescanbeaddedtothesetofmessagessuppliedbytheDITA-OT.ThesemessagescanthenbeusedbyanyXSLToverride.

dita.xsl.messages

Addnewmessagestodiagnosticmessagefile.

Example

Toaddyourownmessages,createthenewmessagesinanXMLfilesuchasmyMessages.xml:

<dummy>



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

<reason>Messagetext</reason>

<response>Howtoresolve</response>

</message>

</dummy>

TherearethreecomponentstothemessageID:

1. TheprefixDOTXisusedbyallDITA-OTXSLTtransforms,andmustbepartoftheID.

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

3. Finally,alettercorrespondstotheseverity.Thisshouldbeoneof:

I=Informational,usedwithtype="INFO"

W=Warning,usedwithtype="WARN"

E=Error,usedwithtype="ERROR"

F=Fatal,usedwithtype="FATAL"

Oncethemessagefileisdefined,itisincorporatedwiththisextension:

<pluginid="com.example.newmsg">

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

</plugin>

XSLTmodulescanthengeneratethemessageusingthefollowingcall:

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

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

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

</xsl:call-template>

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

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

<requireplugin="plugin-id">

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

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

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

Example

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

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



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

</plugin>

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

<pluginid="pluginC">



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

</plugin>

VersionandsupportinformationThefollowingextensionpointsareusedbyconventiontodefineversionandsupportinfowithinaplug-in.

package.support.name

package.support.email

package.version

Note:

Thetoolkitdoesnotcurrentlydoanythingwiththesevalues,butmaydosointhefuture.

Thepackage.versionvalueshouldfollowthesyntaxrules:

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

major::=number

minor::=number

micro::=number

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

Thedefaultvalueis0.0.0.

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

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

<featureextension="package.support.email"value="[email protected]"/>

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

</plugin>


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

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

Tomarkanewfileasatemplatefile,usethe<template>element.

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

dita:extensionelement

Thedita:extensionelementsareusedtoinsertgeneratedcontentduringintegrationprocess.Therearetworequiredattributes:

TheidattributedefinestheextensionpointIDwhichprovidestheargumentdata.

Thebehaviourattributedefineswhichprocessingactionisused.

Supportedvaluesforbehaviorattribute:

org.dita.dost.platform.CheckTranstypeAction

CreateAntconditionelementstocheckif${transtype}propertyvalueequalsasupportedtranstypevalue.

org.dita.dost.platform.ImportAntLibAction

CreateAntpathelementelementsforlibraryimportedextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.ImportPluginCatalogAction

Includeplug-inmetadatacatalogcontent.

org.dita.dost.platform.ImportPluginInfoAction

Createplug-inmetadataAntproperties.

org.dita.dost.platform.ImportStringsAction

Includeplug-instringfilecontentbaseongeneratedtextextensionpoint.TheidattributeisusedtodefinetheextensionpointID.

org.dita.dost.platform.ImportXSLAction

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


Exampleplugin.xmlfileThefollowingisasampleofaplugin.xmlfile.ThisfileaddssupportforanewsetofspecializedDTDs,andincludesanoverridefortheXHTMLoutputprocessor.

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

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

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

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

</plugin>


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

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

WhichXHTMLoverridesneedtomigrate?

IfyouroverridedoesnotcontainanycoderelatedtoDITAVALflagging,thenthereisnothingtomigrate.

IfyourbuildsdonotmakeuseofDITAVALbasedflagging,butcallsthedeprecatedflaggingtemplates,thenyoushouldoverridebutthereislittleurgency.Youwillnotseeanydifferenceintheoutput,butthosetemplateswillberemovedinafuturerelease.

IfyoudomakeuseofDITAVALbasedflagging,tryusingyouroverridewith1.7.Checktheelementsyouoverride:

1. Insomecasesflagsmaybedoubled.Thiswillbethecaseifyoucallroutinessuchas"start-flagit".

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

3. Inothercases,flagsmaystillappearproperly,inwhichcasemigrationislessurgent

Foranymigrationthatneedsmigration,pleaseseetheinstructionsthatfollow.

DeprecatedtemplatesinDITA-OT1.7

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

The"gen-style"templateusedtoaddCSSstyling

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

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

Shortcuttemplatesthatgroupthesetemplatesintoasinglecall,suchas:

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

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

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

Allothertemplatesthatmakeuseofthe$flagrulesvariable,whichisnolongerusedinanyoftheDITA-OT1.7code

Alltemplateswithinflag.xslthatwerecalledfromthetemplateslistedabove

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

Whatreplacesthetemplates?

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

Forexample,thecommonlogicformostelementrulesbeforeDITA-OT1.7couldbeboileddowntothefollowing:

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

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

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

Outputendtagsuchas</div>or</span>

Migrating"gen-style"namedtemplate

Callstothe"gen-style"templateshouldbedeleted.Thereisnoneedtoreplacethiscallformostelements.

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

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

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

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

Callstothesetemplatesfallintotwogeneralgroups.

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

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

Createstartingflagandrevisionimages:

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

Createendingflagandrevisionimages:

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

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

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

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

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

<ul>

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

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

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

<xsl:apply-templates/>

</ul>

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

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

</xsl:template>

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

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

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

Migrating"revblock"and"revtext"

Callstothesetwotemplatescanbereplacedwithasimplecallto<xsl:apply-templates/>.

Migratingmodes"outputContentsWithFlags"and"outputContentsWithFlagsAndStyle"

Processinganelementwitheitherofthesemodescanbereplacedwithasimplecallto<xsl:apply-templates/>.

Migratingmode="elementname-fmt"

PriortoDITA-OT1.7,manyelementswereprocessedwiththefollowinglogic:

Matchelement

Setvariabletodetermineifrevisionsareactiveand$DRAFTison

Ifactive

createdivisionwithrevstyle

processelementwithmode="elementname-fmt"

enddivision

Else

processelementwithmode="elementname-fmt"

Matchelementwithmode="elementname-fmt"

Processasneeded

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


CustomizingPDFoutputExampleofPDFoutputcustomizationwithacustomtransformationtype.

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.


<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


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

version="2.0">



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

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

</xsl:stylesheet>

6. AddXSLToverridestocfg/fo/xsl/custom.xsl


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

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

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

version="2.0">



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

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

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

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

<xsl:attributename="id">

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

</xsl:attribute>

</xsl:if>

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

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

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

</fo:block>

</xsl:template>

</xsl:stylesheet>

7. Addvariabledefinitionfilecfg/common/vars/en.xmlforEnglishtooverridegeneratedtext.


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



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

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


InternalAntpropertiesReferencelistofAntpropertiesusedbyDITA-OTinternally.

include.rellinks

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


Implementationdependentfeatures

Chunking

Supportedchunkingmethods:

select-topic

select-document

select-branch

by-topic

by-document

to-content

to-navigation.

Whennochunkattributevaluesaregiven,nochunkingisperformed.

Note:Ineffect,forHTMLbasedtransformationtypesthisisequivalenttoselect-documentandby-documentdefaults.

Errorrecovery:

Whentwotokensfromthesamecategoryareused,noerrororwarningisthrown.

Whenanunrecognizedchunkingmethodisused,noerrororwarningisthrown.

Filtering

Errorrecovery:

Whentherearemultiplerevpropelementswiththesamevalattribute,noerrororwarningisthrown

Whenmultiplepropelementsdefineaduplicateattributeandvaluecombination,attributedefault,orfall-backbehaviour,DOTJ007Eerroristhrown.

Debugattributes

Thedebugattributesarepopulatedasfollows:

xtrf

absolutesystempathofthesourcedocument

xtrc

elementcounterthatusestheformat

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

Imagescaling

Ifbothheightandwidthattributesaregiven,imageisscalednon-uniformly.

Ifscaleattributeisnotanunsignedinteger,noerrororwarningisthrownduringpreprocessing.

Mapprocessing

Whenatopicrefelementthatreferencesamapcontainschildtopicrefelements,DOTX068Werroristhrownandthechildtopicrefelementsareignored.

Linkprocessing

WhenthevalueofhrefattributeisnotavalidURIreference,DOTJ054Eerroristhrown.Dependingonerrorrecovermode,errorrecovermaybeattempted.

Copy-toprocessing

Whenthecopy-toattributeisspecifiedonatopicref,thecontentoftheshortdescelementisnotusedtooverridetheshortdescriptionofthetopic.


ExtendedfunctionalityParenttopic:DITAOpenToolkitDeveloperReference

Codereferenceprocessing

Charsetdefinition

DITA-OTsupportsdefiningthecodereferencetargetfileencodingusingtheformatattribute.Thesupportedformatis:

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

Ifcharsetisnotdefinedsystemdefaultcharsetwillbeused.Ifcharsetisnotrecognizedorsupported,DOTJ052Eerroristhrownandsystemdefaultcharsetisusedasafall-back.

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

Linerangeextraction

Codereferencecanextractonlyagivenlinerangeswithline-rangepointerintheURIfragment.Theformatis:

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

Startandendlinenumbersstartfrom1andareinclusive.Ifendrangeisomitted,rangeendsinlastlineofthefile.

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

Onlylinesfrom5to10willbeincludedintheoutput.

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.


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.


Relatedinformationhttps://lists.sourceforge.net/lists/listinfo/dita-ot-developerhttps://github.com/dita-ot/dita-ot/wiki/Meeting-minutes

https://lists.sourceforge.net/lists/listinfo/dita-ot-developer

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


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


RelatedinformationDITA-OTBugandFeaturetrackeratGitHubSignupfortoolkitdevelopermailinglistHelpwithgettingstartedatGitHub


https://lists.sourceforge.net/lists/listinfo/dita-ot-developer

https://help.github.com/articles/set-up-git

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

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


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.


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


DITAandDITA-OTresourcesInadditiontotheDITA-OTdocumentation,thereareotherresourcesaboutDITAandtheDITA-OTthatyoumightfindhelpful.

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

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

HomepagefortheOASISDITATechnicalCommitteeTheOASISDITATechnicalCommitteedevelopstheDITAstandard.

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

developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.


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

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

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

DITA-OTprojectpageatdita.xml.org

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

Yahoo!dita-usersgroup

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

HomepagefortheOASISDITATechnicalCommittee

TheOASISDITATechnicalCommitteedevelopstheDITAstandard.

Parenttopic:DITAandDITA-OTresources


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

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

developerWorksarticlesBetween2001and2005,IBMDITAexpertspublishedanimportantcollectionofarticlesonthedeveloperWorksWebsite.

IntroductiontotheDarwinInformationTypingArchitecture

SpecializingtopictypesinDITA

SpecializingdomainsinDITA

FrequentlyAskedQuestionsabouttheDarwinInformationTypingArchitecture

WhyuseDITAtoproduceHTMLdeliverables?

DesignpatternsforinformationarchitecturewithDITAmapdomains

MigratingHTMLtoDITA,Part1:SimplestepstomovefromHTMLtoDITA

MigratingHTMLtoDITA,Part2:Extendthemigrationformorerobustresults

TransformEclipsenavigationfilestoDITAnavigationfiles

Parenttopic:DITAandDITA-OTresources

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

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





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

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

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

generate.outer.copyparameterElaborationonhowthegenerate.outer.copyparameterfunctions.

Background

Thisisanissueinthefollowingsituations:

TheDITAmapisinadirectorythatisapeertodirectoriesthatcontainreferencedobjects.

TheDITAmapisinadirectorythatisbelowthedirectoriesthatcontainthereferencedobjects.

Let'sassumethatthedirectorystructurefortheDITAcontentlookslikethefollowing:

maps

topics

images

TheDITAmapisinthemapsdirectory,thetopicsareinthetopicsdirectory,andtheimagesareintheimagesdirectory.

Settingthegenerate.outer.copyparameterto1

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


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.


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

DITA Open Toolkit 1.8 - documentation.helpThe DITA Open Toolkit (DITA-OT) is an open-source...

Documents

Transcript of DITA Open Toolkit 1.8 - documentation.helpThe DITA Open Toolkit (DITA-OT) is an open-source...