countingyoutubemp3mp4

XMLmindDITAConverterManualHusseinShafieXMLmindSoftware35,rueLouisLeblanc78120RambouilletFrancePhone:+33(0)952808037ditac-support@xmlmind.
comwww.
xmlmind.
com/ditac/November30,2020XMLmindDITAConverterManualTableofContentsListofFiguresiiListofTablesiiiIntroductionivPartI.
UsingXMLmindDITAConverter1Chapter1.
InstallingXMLmindDITAConverter21.
Contentsoftheinstallationdirectory3Chapter2.
Gettingstarted61.
Usingtheditaccommand-lineutility6Chapter3.
Theditaccommand-lineutility14Chapter4.
XSLTstylesheetsparameters221.
Pageheadersandfooters49Chapter5.
Controllingthenumberingoforderedlists54Chapter6.
Givingabackgroundcolortotablecells55Chapter7.
Fancycodeblocks561.
Syntaxhighlighting58Chapter8.
Richmediacontent60PartII.
CustomizingtheoutputofXMLmindDITAConverter67Chapter9.
Simplecustomization681.
Customizethelookofthe(X)HTMLpagesgeneratedbyditac682.
CustomizingthelookofthePDFfilesgeneratedbyditac69Chapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecialization71Chapter11.
Extensivecustomization75PartIII.
EmbeddingXMLmindDITAConverterinaJavaapplication82Chapter12.
High-levelmethod:embeddingcom.
xmlmind.
ditac.
convert.
Converter83Chapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessor.
.
.
.
.
.
85AppendixA.
AboutDITAsupportinXMLmindDITAConverter90AppendixB.
LightweightDITAsupport921.
XDITAsupport922.
HDITAsupport923.
MDITAsupport943.
1.
Markdownextensions96AppendixC.
Limitationsandimplementationspecificities109AppendixD.
Translatingthemessagesgeneratedbyditac117IndexiiXMLmindDITAConverterManualListofFigures1.
XMLmindXSLUtilitymainwindowiv2-1.
XMLmindXSLUtilitymainwindow64-1.
Pageareas494-2.
Layoutofaheader508-1.
MynameisHubble.
I'ma7-montholdGoldenRetriever.
6611-1.
Theintermediatefilesgeneratedbytheditacpreprocessor75iiXMLmindDITAConverterManualListofTables2-1.
Supportedfilenameextensions72-2.
Supportedoutputformats9B-1.
Tablecaptionhere106iiiXMLmindDITAConverterManualIntroductionXMLmindDITAConverter(ditacforshort)allowstoconvertthemostcomplexDITA1.
0,1.
1.
1.
2and1.
3documentstoproduction-qualityXHTML1.
0,XHTML1.
1,HTML4.
01,WebHelp,JavaHelp,HTMLHelp,EclipseHelp,EPUB,PDF,PostScript,RTF(canbeopenedinWord2000+),WordprocessingML(canbeopenedinWord2003+),OfficeOpenXML(.
docx,canbeopenedinWord2007+),OpenOffice(.
odt,canbeopenedinOpenOffice/LibreOffice2+).
Thefirstpartofthisdocumentexplainshowtoinstallanduseditac.
ThetargetaudienceforthispartistheDITAauthor.
Thesecondpartofthisdocumentexplainshowtocustomizetheoutputofditac.
ThetargetaudienceforthispartistheDITAconsultant.
ThethirdpartofthisdocumentexplainshowtoembedditacinaJavaapplication.
ThetargetaudienceforthispartistheJavaprogrammer.
You'llfindattheendofthisdocumentanappendixdetailingthelimitationsandimplementationspecificitiesofditac.
Pleaserefertothisappendixbeforepostingsupportrequeststotheditac-support@xmlmind.
com,public,moderated,mailinglist.
TipXMLmindDITAConverterhasbeenintegratedtoXMLmindXSLUtility,whichispartoftheXMLmindXSL-FOConvertercommercialproduct.
Unlikeditac,whichisacommand-lineutility,XMLmindXSLUtilityisagraphicaltool.
ItmakesiteasyparameterizingtheDITAconversionprocessandthenperformingdocumentconversions.
Figure1.
XMLmindXSLUtilitymainwindowivXMLmindDITAConverterManualMoreover,thisgraphicaltoolcomesinaWindows,auto-installable,self-contained,set-up.
exedistribution(1)whichincludesApacheFOP,XMLmindXSL-FOConverteranddi-tac.
Ifyoujustwanttoquicklyandeasilyevaluateallthepotentialofditac,youmaywanttodownloadXMLmindXSLUtilityEvaluationEditionfromXMLmindXSL-FOConverterwebsite.
DonotbesurprisedbecauseXMLmindXSLUtilityEvaluationEditiongeneratesoutputcontainingrandomduplicateletters.
Ofcourse,thisdoesnothappenwithProfes-sionalEdition!
(1)Ofcourse,a.
zipdistributionisalsoavailableforplatformsotherthanWindows.
vXMLmindDITAConverterManualPartI.
UsingXMLmindDITAConverterPartI.
UsingXMLmindDITAConverter1XMLmindDITAConverterManualChapter1.
InstallingXMLmindDITAConverterBeforeyoubeginXMLmindDITAConverter(ditacforshort)requiresusingaJava1.
8+runtime.
OnUnix,makesurethattheJavabin/directoryisreferencedinthe$PATHand,atthesametime,checkthattheJavaruntimeinthe$PATHhastherightversion:$java-versionopenjdkversion"15.
0.
1"2020-10-20OpenJDKRuntimeEnvironment(build15.
0.
1+9-18)OpenJDK64-BitServerVM(build15.
0.
1+9-18,mixedmode)OnWindowsandontheMac,thisverificationisinprinciplenotneededasthejavaexecutableisautomat-icallyfoundinthe$PATHwhenJavahasbeenproperlyinstalled.
Procedure1.
Unzipthedistributioninanydirectoryyouwant.
C:\>mkdirditacC:\>cdditacC:\ditac>unzipditac-3_8_1.
zipC:\ditac>dirditac-3_8_1.
.
.
bin.
.
.
doc.
.
.
docsrc.
.
.
XMLmindDITAConverterisintendedtobeuseddirectlyfromtheditac-3_8_1/directory.
Thatis,youcanruntheditaccommandbysimplyexecuting(inaCommandPromptonwindows,aterminalonUnix):C:\ditac>ditac-3_8_1\bin\ditac2.
Dependingtheoutputformatsyouwanttogenerate,you'llneedtodownloadandinstallthird-partyexternaltools.
IfyouwanttogeneratePDForPostScript,downloadandinstallApacheFOP.
Alternatively,youmayprefertopurchaseRenderXXEPorAntennaHouseFormatter.
NotethatRenderXXEPPersonalEditionisfreetouse.
WARNINGPleaseinstallanduseeitherApacheFOP1.
1orFOP2.
1+.
PleasedonotinstallanduseApacheFOP2.
0aswehavefoundthisversiontohaveaseverebug(FOP-2461).
Chapter1.
InstallingXMLmindDITAConverter2XMLmindDITAConverterManualNoteIfyouhaveinstalledApacheFOPandyourDITAdocumentcontainMathML,you'llwanttoalsoinstalltheJEuclidFOPplug-in.
Thisplug-inisneededtoaddMathMLsupporttoApacheFOP.
IfyouwanttogenerateRTF(canbeopenedinWord2000+),WordprocessingML(canbeopenedinWord2003+),OfficeOpenXML(.
docx,canbeopenedinWord2007+)orOpenOffice(.
odt,canbeopenedinOpenOffice/LibreOffice2+),thenyouneedtopurchaseXMLmindXSL-FOConverterProfessionalEdition.
YoucangiveXMLmindXSL-FOConverteratrybydownloadingEvaluationEditionfromXML-mindXSL-FOConverterwebsite.
DonotbesurprisedbecauseXMLmindXSL-FOConverterEvaluationEditiongeneratesoutputcontainingrandomduplicateletters.
Ofcourse,thisdoesnothappenwithProfessionalEdition!
IfyouwanttogenerateHTMLHelp,downloadandinstalltheHTMLHelpWorkshop(containshhc.
exe).
IfyouwanttogenerateJavaHelp,downloadandinstallJavaHelp(containsjhindexerandjhindexer.
bat).
3.
Ifyouhaveinstalledanyoftheaboveexternaltools,youneednowtoinstructditacwheretofindthem.
Thiscanbedoneusingthefollowingcommandlineoptions:-fop,-xep,-ahf,-xfc,-jhindexer,-hhc.
However,itismuchmoreconvenienttospecifythesecommand-lineoptionsonceforallinaditac.
optionsfile.
a.
Createditac.
options,aplaintextfileencodedusingthenativeencodingoftheplatform(e.
g.
Windows-1252onaWesternWindowsPC),intheditacuserpreferencesdirectory.
Theditacuserpreferencesdirectoryis:$HOME/.
ditac/onLinux.
$HOME/Library/ApplicationSupport/XMLmind/ditac/ontheMac.
%APPDATA%\XMLmind\ditac\onWindows.
Example:C:\Users\john\AppData\Roam-ing\XMLmind\ditac\.
b.
Addtheequivalentofacommand-lineoptionforeachexternaltoolinstalledintheprecedingstep.
Useoneormorenewlinecharacterstoseparatetheoptions.
MoreinformationinTheditac.
op-tionsfile.
-fopE:\opt\fop-2.
5\fop\fop.
bat-xfcE:\opt\xfc_eval_java-6_2_0\bin\fo2rtf.
bat-jhindexerE:\opt\javahelp\javahelp\bin\jhindexer.
bat-hhc"C:\ProgramFiles\HTMLHelpWorkshop\hhc.
exe"1.
Contentsoftheinstallationdirectorybin/ditac,ditac.
batScriptsusedtorunXMLmindDITAConverter(ditacforshort).
UseditaconanyUnixsystem.
Useditac.
batonWindows.
Chapter1.
InstallingXMLmindDITAConverter3XMLmindDITAConverterManualdoc/index.
htmlContainsthedocumentationofditac.
XMLmindDITAConverterManualisavailableinalltheoutputformatssupportedbyditac.
You'llalsofindtherethereferencemanualoftheAPIofditac(generatedbyjavadoc).
docsrc/manual/ContainstheDITAsourceofXMLmindDITAConverterManual.
LEGAL/,LEGAL.
txtContainslegalinformationaboutditacandaboutthird-partycomponentsusedinditac.
lib/Allthe(non-system)Javaclasslibrariesneededtorunditac:ditac.
jarcontainsthecodeofXMLmindDITAConverter.
resolver.
jarisApacheXMLCommonsResolverwhichimplementscatalog-basedentityandURIresolution.
relaxng.
jarisJingversion20030619,JamesClark'sRELAXNGvalidator,slightlymodifiedforuseinXMLmindXMLEditorandXMLmindDITAConverter.
Thedetailsofthemod-ificationsarefoundinLEGAL/relaxng.
README.
saxon9.
jarisMichaelKay'sXSLT2.
0engine.
Seehttp://www.
saxonica.
com/.
whcmin.
jarsnowball.
jarcontainsthecodeneededtorunXMLmindWebHelpCompiler.
xslthl.
jarcontainsthecodeoftheXSLTsyntaxhighlightingopensourcesoftwarecomponent.
flexmark.
jarflexmark-javaisthesoftwarecomponentusedbyditactoparseMarkdownandconvertittoHTML.
plus/Thisdirectoryispresentonlyinthecaseoftheditac-N_N_N-plus-fop.
zipdistribution.
ItcontainsmostrecentApacheFOP(includinghyphenationandMathMLsupport).
ThisXSL-FOprocessorisautomaticallydeclaredandthus,readytobeusedtogeneratePDForPostScript.
schema/ContainstheDTD,RELAXNGandW3CXMLschemasofDITA1.
31.
2,1.
1,1.
0.
1.
Fileschema/catalog.
xmlcontainsanXMLcatalogwhichpointstotheselocalcopies.
src/ContainstheJavasourcecodeofditac.
src/build.
xmlisanantbuildfilewhichallowstorebuildlib/ditac.
jar.
whc_template/ContainsthetemplatedirectoryofXMLmindWebHelpCompiler.
xsl/ContainstheXSLT2.
0stylesheetsusedtoconvertDITAdocumentstoavarietyofformats.
Chapter1.
InstallingXMLmindDITAConverter4XMLmindDITAConverterManualfo/fo.
xslUsedtogenerateanintermediateXSL-FOfile.
Afterthat,theXSL-FOfileisconvert-edtoPDF,PostScript,RTF,WordprocessingML,OfficeOpenXML(.
docx)orOpenOffice/LibreOffice(.
odt)bythemeansofanXSL-FOprocessor.
xhtml/xhtml.
xslUsedtogenerateXHTML1.
0pages.
xhtml/xhtml1_1.
xslUsedtogenerateXHTML1.
1pages.
xhtml/html.
xslUsedtogenerateHTML4.
01pages.
xhtml/xhtml5.
xslUsedtogenerateXHTML5pages.
webhelp/webhelp.
xslUsedtogenerateWebHelpcontainingXHTML1pages,whicharethencompiledusingXMLmindWebHelpCompiler.
webhelp/webhelp5.
xslUsedtogenerateWebHelpcontainingXHTML5pages,whicharethencompiledusingXMLmindWebHelpCompiler.
htmlhelp/htmlhelp.
xslUsedtogenerateHTMLHelpfiles,whicharethencompiledusinghhc.
exe.
eclipsehelp/eclipsehelp.
xslUsedtogenerateEclipseHelpfiles.
javahelp/javahelp.
xslUsedtogenerateJavaHelpfiles,whicharethenarchivedina.
jarfile.
epub/epub.
xslUsedtogenerateEPUB2files,whicharethenarchivedina.
epubfile(Ziparchivehavinga.
epubextension).
epub/epub3.
xslUsedtogenerateEPUB3files,whicharethenarchivedina.
epubfile(Ziparchivehavinga.
epubextension).
hdita/hdita.
xslTranslatesXHTML5toDITAaccordingtotheHDITAspecification.
Chapter1.
InstallingXMLmindDITAConverter5XMLmindDITAConverterManualChapter2.
Gettingstarted1.
Usingtheditaccommand-lineutilityInthischapter,we'llexplainhowtoruntheditaccommand-lineutilitybyusingexamples.
You'llfindalltheDITAinputfilesusedtorunthefollowingexamplesintheditac_install_dir/docsrc/manual/directory.
TipXMLmindDITAConverterhasbeenintegratedtoXMLmindXSLUtility,whichispartoftheXMLmindXSL-FOConvertercommercialproduct.
Unlikeditac,whichisacommand-lineutility,XMLmindXSLUtilityisagraphicaltool.
ItmakesiteasyparameterizingtheDITAconversionprocessandthenperformingdocumentconversions.
Figure2-1.
XMLmindXSLUtilitymainwindowMoreover,thisgraphicaltoolcomesinaWindows,auto-installable,self-contained,set-up.
exedistribution(2)whichincludesApacheFOP,XMLmindXSL-FOConverteranddi-tac.
Ifyoujustwanttoquicklyandeasilyevaluateallthepotentialofditac,youmaywanttodownloadXMLmindXSLUtilityEvaluationEditionfromXMLmindXSL-FOConverterwebsite.
DonotbesurprisedbecauseXMLmindXSLUtilityEvaluationEditiongeneratesoutputcontainingrandomduplicateletters.
Ofcourse,thisdoesnothappenwithProfes-sionalEdition!
(2)Ofcourse,a.
zipdistributionisalsoavailableforplatformsotherthanWindows.
Chapter2.
Gettingstarted6XMLmindDITAConverterManualConvertingadocumenttoPDFConvertingadocumenttoPDFisdonebyexecutingthefollowingcommand:$ditacout/manual.
pdfmanual.
ditamapTheoutputdirectoryout/isautomaticallycreatedifitdoesnotalreadyexist.
Unlessyouhavespecifiedintheditac.
optionsfilewhichXSL-FOprocessortouse,you'llhavetoexecute:$ditac-fop/opt/fop/fopout/manual.
pdfmanual.
ditamapor:$ditac-xep/opt/xep/xepout/manual.
pdfmanual.
ditamapor:$ditac-ahf"C:\AHFv6\AHFCmd.
exe"out/manual.
pdfmanual.
ditamapTipNoneedtodeclareApacheFOPusingthe-fopcommand-lineoptionifyouhaveinstalledthedistributioncalledditac-N_N_N-plus-fop.
zip.
Thisdistributioncontainsmostre-centApacheFOP(includinghyphenationandMathMLsupport).
ThisXSL-FOprocessorisautomaticallydeclaredandthus,readytobeusedtogeneratePDForPostScript.
TheXSL-FOprocessorsallowingtogeneratePDFalsoallowstogeneratePostScript.
Example:$ditacout/manual.
psmanual.
ditamapNoticehowtheoutputformatisdeterminedbyexaminingthefilenameextensionoftheoutputfile.
Table2-1.
SupportedfilenameextensionsFormatExtensionsXHTML1.
0.
html,.
htm,.
xhtmlEPUB2.
epubHTMLHelp.
chmJavaHelp.
jarPDF.
pdfPostScript.
psRTF(canbeopenedinWord2000+).
rtf,.
docWordprocessingML(canbeopenedinWord2003+).
wml,.
xmlOfficeOpenXML(canbeopenedinWord2007+).
docxOpenOffice(canbeopenedinOpenOffice/Libre-Office2+).
odtChapter2.
Gettingstarted7XMLmindDITAConverterManualNotethatditacalsoallowstoconvertoneormoretopicfilesratherthanasinglemaporbookmapfile:$ditac-toc\out/draft.
pdfembed1.
ditaembed2.
ditaDitacdoesnotgenerateatableofcontents(TOC)bydefault.
Unlesstheinputfileisabookmapcontaininganemptytocelementinitsfrontmatter/booklistsdescendantelement,you'llhavetoexplicitlyusethe-tocoption.
Usingthe-tocoptionwhentheinputfilealreadyspecifiesaTOCisharmless,soyoucouldaswelladda-toclinetoyourditac.
optionsfile.
ConvertingadocumenttoawordprocessorformatConvertingadocumenttoawordprocessorformatjustrequirestheuseofanXSL-FOprocessordifferentfromtheonewhichgeneratesPDForPostScript.
Fortunatelyallthisautomaticallyhandledbyditac.
ConvertadocumenttoRTF(canbeopenedinWord2000+):$ditacout/manual.
rtfmanual.
ditamapUnlessyouhavespecifiedintheditac.
optionsfilewhichXSL-FOprocessortouse,you'llhavetoexecute:$ditac-xfc/opt/xfc/fo2rtfout/manual.
rtfmanual.
ditamapSufficetospecifythelocationoffo2rtf(fo2rtf.
batonWindows).
Usingthislocation,ditacinfersthelocationsoffo2wml,fo2docxandfo2odt.
WARNINGXMLmindXSL-FOConverterEvaluationEdition(downloadpage)generatesoutputcon-tainingrandomduplicateletters.
ThismakesthiseditionuselessforanypurposeotherthanevaluatingXMLmindXSL-FOConverter.
Ofcourse,thisdoesnothappenwithXMLmindXSL-FOConverterProfessionalEdition!
ConvertadocumenttoWordprocessingML(canbeopenedinWord2003+):$ditacout/manual.
xmlmanual.
ditamapConvertadocumenttoOfficeOpenXML(canbeopenedinWord2007+):$ditacout/manual.
docxmanual.
ditamapConvertadocumenttoOpenOffice(canbeopenedinOpenOffice.
org2+):$ditac-v-pnumberall\out/manual.
odtmanual.
ditamapUsefuloptions-vinstructsditactoprintprogressmessagesontheconsole.
Recommendedwhenconvertinglargedocuments.
"-pnumberall"passesparameter"number"withvalue"all"totheXSLTstylesheetswhichgeneratetheXSL-FO.
TheXSL-FOarethenconvertedtoOpenOfficeformatbytheChapter2.
Gettingstarted8XMLmindDITAConverterManualmeansofXMLmindXSL-FOConverter.
Thenumber='all'parameterinstructstheXSLTstylesheetstonumbertopics,tablesandfigures.
ConvertingadocumenttoXHTMLConvertingadocumenttomulti-pageXHTML1.
0isdonebyexecutingthefollowingcommand:$ditac-imagesimg-pxsl-resources-directoryres\out/manual/_.
htmlmanual.
ditamapAllthefilesgeneratedbyditacarecreatedintheout/manual/directory.
"-imagesimg"instructsditactocopyalltheimagefilesreferencedbytheinputDITAdocumenttoout/manual/img/.
Specifyingthe-imagesoptionwhengeneratinganoutputformatbasedonXHTML/HTMLisneededinalmostalltheusecases.
"-pxsl-resources-directoryres"instructsditactocopyalltheresourcesneededbytheXSLTstylesheets(CSSstylesheet,navigationicons,etc)toout/manual/res/.
Specifyingavalueforthexsl-resources-directoryparameterwhengeneratinganoutputformatbasedonXHTML/HTMLisneededinalmostalltheusecases.
Noticethestrangenameoftheoutputfile:out/manual/_.
html.
Infact,thisnameisjustusedtospecifythefilenameextensionoftheoutputfiles.
Theactualbasenamesoftheoutputfilesaredeter-minedbyexaminingthechunkandcopy-toattributespossiblyspecifiedintheDITAmap.
Notethatacommand-linelike:$ditac-imagesimg-pxsl-resources-directoryres\out/manual/foo.
htmlmanual.
ditamapworksfinetoo.
Theonlydifferenceisthatinsuchcase,whenabasenameisneededandcannotbede-terminedbyexaminingthechunkandcopy-toattributesspecifiedintheDITAmap,ditacwilluse"foo"asabasenameandyoumayenduphavingsomeoutputfilescalledfoo.
html,foo-2.
html,foo-3.
html,etc.
Whenthebasenameisspecifiedas"_",itisthebasenameoftheDITAmapwhichisused.
Thatis,youmayhavesomeoutputfilescalledmanual.
html,manual-2.
html,manu-al-3.
html,etc.
WhatifyouwanttoconvertadocumenttoHTML4.
01orXHTML1.
1orXHTML5ratherthantoXHTML1.
0Wehavelearnedthatthereisnowaytospecifythisusingafilenameextension.
Theansweris:usethe-formatoption(or-finitsshortform).
Example:$ditac-formathtml\-imagesimg-pxsl-resources-directoryres\out/manual/_.
htmlmanual.
ditamapTable2-2.
SupportedoutputformatsFormatNameXHTML1.
0xhtmlXHTML1.
1xhtml1.
1HTML4.
01htmlXHTML5xhtml5.
html5isanaliasforxhtml5.
Chapter2.
Gettingstarted9XMLmindDITAConverterManualFormatNameWebHelpcontainingXHTML1pageswebhelpWebHelpcontainingXHTML5pageswebhelp5HTMLHelphtmlhelpEclipseHelpeclipsehelpEPUB2epubEPUB3epub3JavaHelpjavahelpPDFpdfPostScriptpsRTF(canbeopenedinWord2000+)rtfWordprocessingML(canbeopenedinWord2003+)wmlOfficeOpenXML(canbeopenedinWord2007+)docxOpenOffice(canbeopenedinOpenOffice.
org2+)odtXSL-FOfoUsefuloptions"-pchain-pagesboth".
ThisXSLTstylesheetparameterspecifiesthataheaderandafootercontainingnavigationiconsshouldbegeneratedinordertolinktogetheralltheHTMLpages.
"-pchain-topicsyes".
ThisXSLTstylesheetparameterspecifiesthatnavigationiconsshouldbegeneratedinordertolinktogetherallthetopics.
"-pdefault-table-width100%".
UnlessthisXSLTstylesheetparameterisspecified(ortheexpanse="page"attributeisspecifiedforalltables),webbrowserstendtolayoutthegeneratedHTMLtablesinordertomakethemasnarrowaspossible.
Afull-fledgedcommand-lineisthus:$ditac-imagesimg-pxsl-resources-directoryres\-pnumberall\-pchain-pagesboth\-pchain-topicsyes\-pdefault-table-width100%\out/manual/_.
htmlmanual.
ditamapWhatifyouwanttogenerateasingleXHTMLpageratherthanmultipleXHTMLpageNoneedtocreateanewDITAmapforthat.
Simplyspecifyoption"-chunksingle"(or-cinitsshortform).
$ditac-chunksingle\-imagesimg-pxsl-resources-directoryres\out/manual.
htmlmanual.
ditamapChapter2.
Gettingstarted10XMLmindDITAConverterManualConvertingadocumenttoWebHelpConvertingadocumenttoWebHelpissimilartoconvertingadocumenttomulti-pageXHTML1.
Themaindifferenceisthatyouneedtoexplicitlyspecify-formatwebhelp:$ditac-formatwebhelp\-imagesimg-pxsl-resources-directoryres\webhelp/_.
htmlmanual.
ditamapIfyouprefertogenerateWebHelpcontainingXHTML5pagesratherthanXHTML1pages,thenspecify-formatwebhelp5.
RememberDonotspecifyanyofthefollowingcommand-lineoptionswhengeneratingWebHelp:-toc,-index.
ConvertingadocumenttoHTMLHelpConvertingadocumenttoHTMLHelpisdonebyexecutingthefollowingcommand:C:\>ditac-imagesimg-pxsl-resources-directoryres\out\manual.
chmmanual.
ditamapUnlessyouhavespecifiedintheditac.
optionsfilethelocationofhhc.
exe,you'llhavetoexecute:C:\>ditac-hhc"C:\ProgramFiles\HTMLHelpWorkshop\hhc.
exe"\-imagesimg-pxsl-resources-directoryres\out\manual.
chmmanual.
ditamapRememberDonotspecifyanyofthefollowingcommand-lineoptionswhengeneratingHTMLHelp:-toc,-index.
ConvertingadocumenttoJavaHelpConvertingadocumenttoJavaHelpisdonebyexecutingthefollowingcommand:$ditac-imagesimg-pxsl-resources-directoryres\out/manual.
jarmanual.
ditamapUnlessyouhavespecifiedintheditac.
optionsfilethelocationofjhindexer(jhindexer.
batonWindows),you'llhavetoexecute:$ditac-jhindexer/opt/jh2.
0/javahelp/bin/jhindexer\-imagesimg-pxsl-resources-directoryres\out/manual.
jarmanual.
ditamapChapter2.
Gettingstarted11XMLmindDITAConverterManualRememberDonotspecifyanyofthefollowingcommand-lineoptionswhengeneratingJavaHelp:-toc,-index.
ConvertingadocumenttoEclipseHelpConvertingadocumenttoEclipseHelpissimilartoconvertingadocumenttomulti-pageXHTML.
Themaindifferenceisthatyouneedtoexplicitlyspecify-formateclipsehelp:$ditac-formateclipsehelp\-imagesimg-pxsl-resources-directoryres\out/com.
acme.
widget.
userguide/_.
htmlmanual.
ditamapInordertodeploythegeneratedEclipseHelp,youneedtocopytheoutputdirectoryasawhole(com.
acme.
widget.
userguide/inthecaseoftheaboveexample)totheplugins/directoryofEclipseandthenuseatextorXMLeditortomodifythegeneratedoutput_directory/plugin.
xml:Ifyoudonotwanttohandeditplugin.
xml,sufficetopassextraXSLTstylesheetparameterstoditac:$ditac-formateclipsehelp\-pplugin-name"ACMEWidgetUser'sGuide"\-pplugin-idcom.
acme.
widget.
userguide\-pplugin-provider"ACMECorp.
"\-imagesimg-pxsl-resources-directoryres\out/com.
acme.
widget.
documentation/_.
htmlmanual.
ditamapRememberIfyouwanttoseeyourdocumentbyselectingHelp→HelpContentsinEclipse:1.
Donotspecifyanyofthefollowingcommand-lineoptionswhengeneratingEclipseHelp:-toc,-index.
2.
Parameterplugin-idisrequiredtohavethesamevalueasthebasenameofthetheout-putdirectory(com.
acme.
widget.
userguide/inthecaseoftheaboveexample).
Chapter2.
Gettingstarted12XMLmindDITAConverterManual3.
Copythisoutputdirectorytoeclipse_install_dir/dropins/andnoteclipse_install_dir/plugins/.
ConvertingadocumenttoEPUBConvertingadocumenttoEPUBHelpisdonebyexecutingthefollowingcommand:$ditac-imagesimg-pxsl-resources-directoryres\out/manual.
epubmanual.
ditamapIfyouprefertogenerateEPUB3ratherthanEPUB2,thenspecify-formatepub3.
RememberDonotspecifyanyofthefollowingcommand-lineoptionswhengeneratingEPUB:-toc.
Notethatyoumayspecifyoption-index.
RelatedinformationChapter3.
Theditaccommand-lineutilityChapter2.
Gettingstarted13XMLmindDITAConverterManualChapter3.
Theditaccommand-lineutilityditac[option]*output_file[in_dita_file]+Command-lineusageConvertsspecifiedDITAinputfilestospecifiedoutputfile.
Theinputfilesmustcompriseasinglemaporbookmapfileorpossiblyseveral,possiblymulti-topic,topicfiles.
Example:converttheuserguide.
ditamapmaptomulti-pageXHTML:C:\docsrc>ditac-pcenter"figtable".
.
\doc\userguide.
htmuserguide.
ditamapExample:converttheintroduction.
ditaandquickstart.
ditatopicstoPDF:C:\docsrc>ditacdraft1.
pdfintroduction.
ditaquickstart.
ditaAninputfilemaybespecifiedusingitsURLoritsfilename.
Theoutputdirectoryiscreatedifitdoesnotalreadyexist.
Insomecase,thereisnoneedtospecifyarealoutputfilename:theoutputdirectoryandtheextensionoftheoutputfilessuffice.
Insuchcase,specify"_"asthebasenameoftheoutputfile.
Example:convertfoo.
ditamaptomulti-pageXHTML.
TheXHTMLpagesmustbegeneratedinthebar/subdirectory.
C:\docsrc>ditacbar\_.
htmlfoo.
ditamapIntheabovecase,thebasenamesofthegeneratedXHTMLpageswillbetakenfromthe@chunkand@copy-toattributesspecifiedinfoo.
ditamapifany,andfromthebasenameofthemap("foo"inthecaseofourexample)otherwise.
Commonlyusedcommand-lineoptionsSomeoptionshavebothashortnameandalongname.
Example:-pisequivalentto-param.
-pparam_nameparam_value-paramparam_nameparam_valueSpecifiesaconversionparameter,generallyanXSLTstylesheetparameter.
SeeChapter4.
Aparam_namestartingwith"load.
doc_loader_name.
"specifiesanoptionwhichispassedtothealternatedocumentloadercalleddoc_loader_name.
Forexample,-pload.
mdita.
au-tolinktrueturnsontheautolinkextensionintheMDITAloader.
SeeMDITAsupport.
-tXSLT_stylesheet_URL_or_file-xsltXSLT_stylesheet_URL_or_fileUsethespecifiedcustomXSLTstylesheetratherthanthestockone.
-cnone|single|auto-chunknone|single|autoThe"none"and"single"valuesmaybeusedtoforcethegenerationofasingleoutputfile.
Forexample,"-chunksingle"allowsthereuseofamapdesignedtooutputmultipleHTMLpagesinordertogenerateaPDFfile.
Chapter3.
Theditaccommand-lineutility14XMLmindDITAConverterManualForexample,"-chunknone"allowsthereuseofamapdesignedtooutputaPDFfileinordertogenerateasingleHTMLpage.
Bydefault,thechunkmodeisautowhichmeans:generateasingleoutputfile(implicit"-chunknone")forformatssuchaspdf,ps,rtf,etc,andgeneratemultipleoutputfilesforformatssuchashtml,xhtml,javahelp,etc.
-fxhtml|xhtml1.
1|html|xhtml5|html5|webhelp|webhelp5|epub|epub3|javahelp|htmlhelp|ps|pdf|rtf|odt|wml|docx|fo-formatxhtml|xhtml1.
1|html|xhtml5|html5|webhelp|webhelp5|epub|epub3|javahelp|htmlhelp|ps|pdf|rtf|odt|wml|docx|foExplicitlyspecifiestheoutputformat.
Bydefault,theoutputformatisdeterminedusingtheex-tensionofoutput_file.
Notes:A"htm"or"html"filenameextensionimplicitlyspecifiesanXHTML1.
0outputformat,andnotanHTML4.
01outputformat.
InordertogenerateHTML4.
01,explicitlyspecify"-fhtml".
Thesameremarkappliestoxhtml1.
1,xhtml5,webhelp,webhelp5.
Optionhtml5issimplyanaliasforxhtml5.
Optionwebhelp5meansWebHelpcontainingXHTML5pagesratherthanXHTML1pages.
OptionepubspecifiestheEPUB2format.
-rresource_path-resourcesresource_path-iresource_path-imagesresource_pathCopytheresourcefiles,typicallyimagefiles,referencedinthesourcetopicstospecifieddirectory.
Ifspecifiedpathisrelative,itisrelativetotheoutputdirectory.
-resourcehandlerclass_nameparametersPasstheresourcefiles,typicallyimagefiles,referencedinthesourcetopicstoclass_name,aJavaclassimplementinginterfacecom.
xmlmind.
ditac.
preprocess.
ResourceHandler.
StringparametersisusedtoconfigurethenewlycreatedResourceHandler.
Forexample,"-rres"isequivalentto"-resourcehandlercom.
xmlmind.
ditac.
con-vert.
ResourceCopierres".
-filterditaval_URL_or_fileApplyspecifiedconditionalprocessingprofile(.
ditavalfile)tothetopics.
-attrvaluessubject_scheme_map_URL_or_fileSpecifyanexternalsubjectschememap.
Thecontrolledattributevaluesfoundinthissubjectschememapareprependedtothoseloadedfromthesubjectschememapspossiblyreferencedinthemaporbookmaptobeconverted.
-defaultattrvaluessubject_scheme_map_URL_or_fileSameas-attrvaluesexceptthatthecontrolledattributevaluesfoundinthissubjectschememapwillnotbeusedifsomecontrolledattributevaluesareloadedfromthesubjectschememapsreferencedinthemaporbookmaptobeconverted.
-tocEquivalentto"-frontmattertoc".
Chapter3.
Theditaccommand-lineutility15XMLmindDITAConverterManualNotethatthisoptionwillnotcauseaTableofContentstobegeneratedwhenthemapcontainsasingle(3)havingnodescendants.
-indexEquivalentto"-backmatterindexlist".
-frontmatterspecAutomaticallygeneratespecifiedsections:TableofContents,ListofTables,etc,beforetheotherpages.
Whenusedona,thisoptionaddselementsafteranyexistingelements.
Thesyntaxofspecis:spec->same_page[','same_page]*same_page->section['+'section]*section->'toc'|'figurelist'|'tablelist'|'examplelist'|'equationlist'|'indexlist'Example:generatetheTableOfContentsinitsownpage,followedbyanotherpagecontainingboththeListofFiguresandtheListofTables.
-frontmattertoc,figurelist+tablelist-backmatterspecAutomaticallygeneratespecifiedsections:TableofContents,ListofTables,etc,aftertheotherpages.
See-frontmatterformoreinformation.
Whenusedona,thisoptionaddselementsbeforeanyexistingele-ments.
-addindexWhenanoutputfilecontainstheTableofContents(let'scallthisfilemain.
html)andwhennofilecalledindex.
htmlhasbeengenerated,thisoptioncopiesmain.
htmltoindex.
html.
Appliestoformats:xhtml,xhtml1.
1,html,webhelp.
-langlanguage_codeSpecifiesthemainlanguageofthedocumentShorthandfor:-foconverterpdf"executable_file"-foconverterps"executable_file".
Examples:"fr","fr-CA".
Neededtosorttheindexentries.
Bydefault,thisinformationistakenfromthe@xml:langattributeoftherootelementofthetopicmap(ifany,"en"otherwise).
-v-vv-vvvTurnverbosityon.
MoreVsmeansmoreverbose.
(3)Notcountingscontainedinand.
Chapter3.
Theditaccommand-lineutility16XMLmindDITAConverterManual-ooptions_URL_or_file-optionoptions_URL_or_fileThisoptionletstheuserspecifyatextfilecontainingcommand-linearguments.
Thistextfilehasthesameformatastheditac.
optionsfile.
Example:$ditac-v-ohtml.
optionsfoo.
htmfoo.
ditamapIfhtml.
optionscontains:-formathtml-pcsshttp://www.
acme.
com/css/acme.
cssthenthisisequivalenttorunning:$ditac-v-formathtml-pcsshttp://www.
acme.
com/css/acme.
css\foo.
htmfoo.
ditamapCommand-lineoptionsusedtoconfigureditac-fopexecutable_fileSpecifiesthelocationofthefopshellscript(fop.
batonWindows).
Shorthandfor:-foconverterFOPpdf"executable_file"-q-r-fo"%I"-pdf"%O"-foconverterFOPps"executable_file"-q-r-fo"%I"-ps"%O"-xepexecutable_fileSpecifiesthelocationofthexepshellscript(xep.
batonWindows).
Shorthandfor:-foconverterXEPpdf"executable_file"-quiet-valid-fo"%I"-pdf"%O"-foconverterXEPps"executable_file"-quiet-valid-fo"%I"-ps"%O"-ahfexecutable_fileSpecifiesthelocationofAHFCmd.
exe(run.
shonplatformsotherthanWindows).
Shorthandfor:-foconverterAHFpdf"executable_file"-x3-p@PDF-d"%I\"-o"%O"-foconverterAHFps"executable_file"-x3-p@PS-d"%I"-o"%O"-xfcexecutable_fileSpecifiesthelocationofthefo2rtfshellscript(fo2rtf.
batonWindows).
Sufficetospecifythelocationoffo2rtf.
Usingthislocation,ditacinfersthelocationsoffo2wml,fo2docxandfo2odt.
Shorthandfor:-foconverterXFCrtf"fo2rtf_executable_file""%I""%O"-foconverterXFCwml"fo2wml_executable_file""%I""%O"-foconverterXFCdocx"fo2docx_executable_file""%I""%O"-foconverterXFCodf"fo2odt_executable_file""%I""%O"Chapter3.
Theditaccommand-lineutility17XMLmindDITAConverterManualWARNINGXMLmindXSL-FOConverterEvaluationEdition(downloadpage)generatesoutputcontainingrandomduplicateletters.
ThismakesthiseditionuselessforanypurposeotherthanevaluatingXMLmindXSL-FOConverter.
Ofcourse,thisdoesnothappenwithXMLmindXSL-FOConverterProfessionalEdition!
-foconverterprocessor_nametarget_formatcommandRegisterspecifiedXSL-FOconverterwithditac,alower-levelalternativetousing-xep,-fop,-ahfor-xfc.
Example:-foconverterXFCrtf'/opt/xfc/bin/fo2rtf"%I""%O"'Notethatthisoptioncanbespecifiedseveraltimeswithdifferentvaluesinthesamecom-mand-line.
Thislow-leveloptionmaybeusedforexampletospecifyaconfigurationfileforApacheFOP:-foconverterFOPpdf\'/opt/fop/fop-c/home/john/docs/fop.
conf-q-r-fo"%I"-pdf"%O"'-jhindexerexecutable_fileSpecifiesthelocationofthejhindexershellscript(jhindexer.
batonWindows),theJavaHelpindexer.
-hhcexe_fileSpecifiesthelocationofhhc.
exe,theHTMLHelpcompiler.
-pluginplugin_nameUsetheDTDs/schemasandtheXSLTstylesheetsfoundintheplug-insubdirectoryhavingspeci-fiednamepreferablytothosefoundinditac_install_dir/schema/andinditac_instal-l_dir/xsl/.
SeeWhatisaplug-in.
Command-lineoptionsusedtodebugditac-preprocessStopafterpreprocessinginputfiles.
-automapsave_fileSavetheautomaticallygeneratedtopicmap(ifany)tospecifiedfile.
-keepfoWhengeneratingPDF,RTF,etc,donotdeletethetemporaryXSL-FOfile.
-erroutOutputallmessages,includingerrorsandwarnings,tostdout.
-ignoreoptionsfileDonotloadtheditac.
optionsoptionsfile.
SeebelowTheditac.
optionsfile.
-validateValidatealltheXMLfilesloadedbyditac.
Anyvalidationerrorwillcauseditactoimmediatelystoprunning.
Thereforethecombinationofthe-validateand-dryrunoptionsgivesyouasimplewaytothoroughlycheckyourDITAdocument.
Notethatforthe-validateoptiontowork,alltheXMLfiles(maps,topics,even.
ditavalfilterfiles)loadedbyditacmuststartwiththeproperdeclaration.
Chapter3.
Theditaccommand-lineutility18XMLmindDITAConverterManualThisoptionisunrelatedtoattributevaluevalidationvalidationbythemeansofsubjectschememaps.
Whenthemaptobeconverted(oranyofitssubmaps)referencessomesubjectschememapsthentheattributevaluevalidationisautomaticandcannotbeturnedoff.
-dryrunUseditacasavalidator,andmostnotablycheckcross-references.
Thatis,donotgenerateanyfile;justreporterrorsifany.
-versionPrintversionnumberandexit.
Theditac.
optionsfileItisalsopossibletospecifycommand-lineoptionsintheditac.
optionsoptionsfile.
Thecontentofthisplaintextfile,encodedinthenativeencodingoftheplatform(e.
g.
Windows-1252onaWesternWindowsPC),isautomaticallyloadedbyditaceachtimethiscommandisexecuted.
Thecontentofthisfile,com-mand-lineoptionsseparatedbywhitespace,isprependedtotheoptionsspecifiedinthecommand-line.
Example:Ifditac.
optionscontains:-v-pnumberallRunning:~/docsrc$ditac-pcenter"figtable".
.
/doc/userguide.
htmuserguide.
ditamapisequivalenttorunning:~/docsrc$ditac-v-pnumberall-pcenter"figtable"\.
.
/doc/userguide.
htmuserguide.
ditamapTheditac.
optionsoptionsfileisfoundintheditacuserpreferencesdirectory.
Thisdirectoryis:$HOME/.
ditac/onLinux.
$HOME/Library/ApplicationSupport/XMLmind/ditac/ontheMac.
%APPDATA%\XMLmind\ditac\onWindows.
Example:C:\Users\john\AppData\Roaming\XML-mind\ditac\.
Theditac.
optionsoptionsfileismainlyusefultoconfigureditaconceforallbyspecifyingvaluesforthe-fop,-xep,-xfc,-jhindexer,-hhc,-pluginoptions.
Example:-v-xepE:\opt\xep\xep.
bat-fopE:\opt\fop-2.
5\fop\fop.
bat-xfcE:\opt\xfc_eval_java-6_2_0\bin\fo2rtf.
bat-jhindexerE:\opt\javahelp\javahelp\bin\jhindexer.
bat-hhc"C:\ProgramFiles\HTMLHelpWorkshop\hhc.
exe"RememberRelativefilenamesfoundinthisfilearerelativetothecurrentworkingdirectory,andnottotheditac.
optionsoptionsfile.
Thereforeitisrecommendedtoalwaysspecifyabsolutefilenames.
Chapter3.
Theditaccommand-lineutility19XMLmindDITAConverterManualNocomments(e.
g.
linesstartingwith'#')areallowedinditac.
options.
Optionsmustbeseparatedbywhitespace.
Intheaboveexample,FOPisdeclaredafterXEP.
ThisimpliesthatitisFOPandnotXEP,whichwillbeusedbyditactogeneratePDFandPostScript.
AnXSL-FOprocessortendtoconsumealotofmemory.
IftheDITAconversionfailswithanout-of-memoryerror,youneedtoeditthexep(xep.
bat),fop(fop.
bat),fo2xxx(fo2xxx.
bat)scriptsinordertoincreasethemaximumamountofmemorythattheJavaruntimemayallocate.
Thisisdonebyusingthe-XmxoptionoftheJavacommand-line.
Example:"java.
.
.
-Xmx512m.
.
.
".
StartingfromJava1.
6.
0_23,convertingXMLdocumentstoPDFusingRenderXXEPrandomlyfailswithfalseXSL-FOerrors(e.
g.
attribute"space-before"maynotbeempty).
Thisproblemseemsspecifictothe64-bitruntime.
Theworkaroundsfortheabovebug("renderx#22766")are:–Usea32-bitJavaruntime.
–ORUsea64-bitJavaruntimeolderthan1.
6.
0_23.
–ORSpecifyoption-validinthexepcommand-line.
NotethatthisworkaroundisautomaticallyusedwhenyouspecifywhichRenderXXEPexecutabletousebythemeansofthe-xepcommand-lineoption.
Whatisaplug-inAplug-inissimplyasubdirectoryofditac_install_dir/plugin/.
Forexample,ditac_instal-l_dir/plugin/MyPlugin/.
ThissubdirectorymaycontainanXMLcatalogfile.
ThisXMLcatalogfilemustbenamedcatalog.
xml.
InthecaseofaDITAspecialization,catalog.
xmlpointstolocalcopiesofcustomizedDTDs.
Example:ditac_install_dir/plugin/MyPlugin/catalog.
xml:.
.
.
Thissubdirectorymaycontainanxsl/subdirectoryorganizedexactlylikeditac_install_dir/xsl/.
Thatis,thisxsl/subdirectorymaycontainoneormoreofthefollowingXSLTstylesheets:XSLTstylesheetDescriptionxsl/fo/fo.
xslUsedtogenerateanintermediateXSL-FOfile.
Afterthat,theXSL-FOfileisconvertedtoPDF,PostScript,RTF,WordprocessingML,OfficeOpenXML(.
docx)orOpenOffice/LibreOffice(.
odt)bythemeansofanXSL-FOprocessor.
xsl/xhtml/xhtml.
xslUsedtogenerateXHTML1.
0pages.
xsl/xhtml/xhtml1_1.
xslUsedtogenerateXHTML1.
1pages.
xsl/xhtml/html.
xslUsedtogenerateHTML4.
01pages.
Chapter3.
Theditaccommand-lineutility20XMLmindDITAConverterManualXSLTstylesheetDescriptionxsl/xhtml/xhtml5.
xslUsedtogenerateXHTML5pages.
xsl/webhelp/webhelp.
xslUsedtogenerateWebHelpcontainingXHTML1pages,whicharethencompiledusingXMLmindWebHelpCompiler.
xsl/webhelp/webhelp5.
xslUsedtogenerateWebHelpcontainingXHTML5pages,whicharethencompiledusingXMLmindWebHelpCompiler.
xsl/htmlhelp/htmlhelp.
xslUsedtogenerateHTMLHelpfiles,whicharethencompiledusinghhc.
exe.
xsl/eclipsehelp/eclipsehelp.
xslUsedtogenerateEclipseHelpfiles.
xsl/javahelp/javahelp.
xslUsedtogenerateJavaHelpfiles,whicharethenarchivedina.
jarfile.
xsl/epub/epub.
xslUsedtogenerateEPUB2files,whicharethenarchivedina.
epubfile(Ziparchivehavinga.
epubextension).
xsl/epub/epub3.
xslUsedtogenerateEPUB3files,whicharethenarchivedina.
epubfile(Ziparchivehavinga.
epubextension).
Whenditacispassedcommand-lineoption-pluginplugin_name,itwillusetheDTDs/schemasandtheXSLTstylesheetsfoundintheplug-insubdirectoryhavingspecifiednamepreferablytothosefoundinditac_install_dir/schema/andinditac_install_dir/xsl/.
TipIfyoudon'twantyourplug-instoresideinsideditac_install_dir/plugin/,youmayspecifyanalternateparentdirectorybythemeansoftheDITAC_PLUGIN_DIRenvironmentvariable.
Example:OnWindows:C:\>setDITAC_PLUGIN_DIR=C:\Users\john\ditac_pluginsOnUnix:$exportDITAC_PLUGIN_DIR=/home/john/ditac_pluginsRelatedinformationChapter4.
XSLTstylesheetsparametersChapter3.
Theditaccommand-lineutility21XMLmindDITAConverterManualChapter4.
XSLTstylesheetsparametersParameterscommontoallstylesheetsNoteParametersmarkedusingthisiconaresystemparameters.
TheyareautomaticallyspecifiedbytheapplicationexecutingtheXSLTstylesheets.
Suchsystemparametersmustnotbespecifiedbytheend-user.
Suchsystemparametersaredocumentedhereonlybecausetheend-usermayseethemreferencedinsomeconfigurationfiles.
Parametersmarkedusingthisiconarepseudo-parameters.
TheymayormaynotbepassedtotheXSLTstylesheets,buttheimportantthingtorememberisthattheyarealsointerpretedbyditacitself.
Byconsequence,youcannotspecifytheminanXSLTstylesheetwhichcustomizesthestockones(asexplainedinPartII,Chapter9,Section2).
ParameterValueDescriptionappendix-num-ber-formatAllowedvaluesare:'I','i','A','a','1'.
Defaultvalue:'A'.
Thenumberformatoftopicsreferencedinabookmapasappendix.
Bydefault,suchtopicsarenumberedasfollows:AppendixA.
Titleoffirstappendix,AppendixB.
Titleofsecondappendix,etc.
cause-number-for-matAllowedvaluesare:'I','i','A','a','1'.
Defaultvalue:'A'.
Inatopic,multipleelementshavingnotitlearegivennumbersformattedusingthisformat.
centerListofelementnamesseparatedbywhitespace.
Example:'figequa-tion-figuresim-pletabletable'.
Defaultvalue:''.
Specifieswhichelementsaretobecenteredhori-zontallyonthepage.
ditacListsURIURL(4).
Defaultvalue:out-put_dir/di-tac_lists.
di-tac_lists.
TheURLoffileditac_lists.
ditac_lists.
equation-num-ber-afterString.
Defaultvalue:')'.
Textaddedafterthecontentsofaelement.
(4)Unlikeafilename,anURLmustcontainproperlyquotedcharacters.
Forexample,donotspecify'Helloworld.
ht-m',insteadspecify'Hello%20world.
htm'.
Chapter4.
XSLTstylesheetsparameters22XMLmindDITAConverterManualParameterValueDescriptionequation-num-ber-beforeString.
Defaultvalue:'('.
Textaddedbeforethecontentsofaelement.
extended-tocAllowedvaluesare:'frontmatter','backmatter','both','none'.
Defaultvalue:'none'.
AllowstoaddandstotheTableofContents(TOC)ofadocument.
Notethatthe@toc,@navtitle,@locktitle,etc,attributesareappliednormallytoandswhenanextendedTOCisgenerated.
external-re-source-baseAllowedvaluesare:'',anURLendingwith"/"or'#REMOVE'.
Defaultvalue:'#RE-MOVE'forEPUB2andEPUB3,''foralltheotheroutputformats.
Specifieshowtoresolveorelementshavinganexternal@scopeattributeandarelative@hrefattribute.
Exampleofsuchelements:Test.
java.
''Donotresolvethe@hrefattribute.
Inthiscase,theexternalresourcefilesareexpectedtobecopied"byhand"totheoutputdirectory.
AnURLendingwith"/"ThisURLisprependedtothevalueofthe@hrefattribute.
'#REMOVE'Theorelementisprocessedasifitdidnothavean@hrefattribute.
highlight-sourceAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Allowstoturnoffsyntaxhighlightinginelementsspecializing.
Bydefault,syntaxhighlightingisturnedonforallelementsspecializingandhav-ingan@outputclassattributeequalstolan-guage-c,language-cpp,language-csharp,language-delphi,language-ini,lan-guage-java,language-javascript,lan-guage-m2,language-perl,language-php,language-python,language-ruby,lan-guage-tcl.
index-range-sepa-ratorString.
Defaultvalue:'–'(ENDASH).
Thestringusedtoseparatethefirstpagenumberfromthelastpagenumberinapagerangeofanin-dexedterm.
Example:index-range-separa-tor='':CCat54,8790Chapter4.
XSLTstylesheetsparameters23XMLmindDITAConverterManualParameterValueDescriptionlink-auto-textListofvaluesseparatedbywhitespace.
Allowedvaluesare:'number'and'text'.
Defaultvalue:'numbertext'.
Thisparameterspecifieswhichtexttogenerateforaelement,whenthiselementhasnochildelementorwhenthischildelementisempty.
Similartoaboveparameterxref-auto-textbutforelements.
note-icon-listListoftypeattributevaluesseparatedbywhitespace.
Defaultvalue:'atten-tioncautiondan-gerfastpathim-portantnotenotesrememberrestric-tiontip'.
Specifiesthetype(attribute@type)oftheelementsforwhichiconsshouldbeusedratherthantextinordertorepresentnotelabels.
Ignoredunlessuse-note-icon='yes'.
numberListofvaluesseparat-edbywhitespace.
Al-lowedvaluesare:'top-ic','chapter-on-ly','table','fig','example','equa-tion-figure','all'.
Defaultvalue:''(num-bernothing).
Specifieswhichelementsaretobenumbered.
'all'isashortformfor'topictablefigequation-figure'.
'chapter-only'means:numbertopics,butonlythosereferencedinabookmapas,and.
NotePleasenotethat'all'doesnotinclude'example'.
Ifyouwanttonumberallfor-malelementsincludingex-amples,thenyoumustspec-ify'allexample'.
number-separator1String.
Defaultvalue:'.
'.
Thestringusedtoseparatethehierarchicalnumberoftopicsactingassections.
number-separator2String.
Defaultvalue:'-'.
Thestringusedtoseparatethehierarchicalnumberoffigures,tables,examplesandequations.
Whenpossible,thenumberoffigure,table,exam-pleorequationismaderelativetothenumberoftheancestorchapterorappendix.
Thisgivesforex-ample(fordescendantsofchapter5):Figure5-1.
Titleoffirstfigureofchapter5,Figure5-2.
Titleofsecondfigureofchapter5,etc.
mark-impor-tant-stepsAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Generatesa"Required"(respectively"Optional")labelforandelementshavingChapter4.
XSLTstylesheetsparameters24XMLmindDITAConverterManualParameterValueDescriptionan@importanceattributesetto"required"(re-sp.
"optional").
part-number-formatAllowedvaluesare:'I','i','A','a','1'.
Defaultvalue:'I'.
Thenumberformatoftopicsreferencedinabookmapaspart.
Bydefault,suchtopicsarenumberedasfollows:PartI.
Titleoffirstpart,PartII.
Titleofsecondpart,etc.
prepend-chap-ter-to-sec-tion-numberAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Normallytopicswhicharedescendantsofchapters(thatis,topicsreferencedinabookmapas)arenumberedasfollows:1.
Titleoffirstsection,1.
1.
Titleoffirstsubsection,etc.
Specifyingprepend-chapter-to-sec-tion-number='yes'prependsthenumberofthechapterancestortothesectionnumber.
Thisgivesforexample(fordescendantsofchapter5):5.
1.
Ti-tleoffirstsection,5.
1.
1.
Titleoffirstsubsection,etc.
remedy-number-for-matAllowedvaluesare:'I','i','A','a','1'.
Defaultvalue:'A'.
Inatopic,multipleelementshavingnotitlearegivennumbersformattedusingthisformat.
show-draft-com-mentsAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetherelementsshouldberendered.
troubleSolu-tion-number-formatAllowedvaluesare:'I','i','A','a','1'.
Defaultvalue:'1'.
Inatopic,multipleelementshavingnotitlearegivennumbersformattedusingthisformat.
title-afterListofelementnamesseparatedbywhitespace.
Example:'figequa-tion-figuretable'.
Defaultvalue:''.
Specifieswhichelementsshouldhavetheirtitlesdisplayedaftertheirbodies.
title-pageAllowedvaluesare:'auto','none'ortheURIofacustomtitlepage.
Defaultvalue:'auto'.
Specifiesthekindof``titlepage''(containsthetitleofthedocument,itsauthor,etc)tobegeneratedbe-foretheactualcontentsofthedocument.
'auto'Automaticallygenerateatitlepagebasedonthetitleandmetadataofthemap.
'none'Donotgenerateatitlepage.
Chapter4.
XSLTstylesheetsparameters25XMLmindDITAConverterManualParameterValueDescriptionURIofacustomtitlepageSpecifiestheURIofacustomtitlepage.
IftheURIisrelative,itisrelativetothecurrentworkingdirectoryoftheuser.
ThiscustomtitlepageisanXHTMLfileforXHTML-basedformats(XHTML,HTMLHelp,etc).
ThiscustomtitlepageisanXSL-FOfileforFO-basedformats(PDF,RTF,etc).
Suchcustomtitlepagesaregenerallyhand-written.
Thechildnodesofthebodyel-ementofthecustomXHTMLti-tlepagearewrappedinadivcontainedintheXHTML/HTMLfilebeinggeneratedbytheXSLTstylesheet.
DonotaddatosuchcustomXHTMLtitlepagebecauseotherwise,theXSLTstylesheetmayfailloadingit.
SeesamplecustomXHTMLtitlepage.
Thechildnodesofthefirstfo:flow[@flow-name='xsl-re-gion-body']elementofthecus-tomXSL-FOtitlepagearewrappedinafo:blockcontainedtheXSL-FOfilebeinggeneratedbytheXSLTstylesheet.
SeesamplecustomXSL-FOtitlepage.
title-prefix-sepa-rator1String.
Defaultvalue:'.
'.
Thestringusedtoseparatethenumberofanfor-malobjectfromitstitle.
use-note-iconAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhethericonsshouldbeusedratherthantextinordertorepresentthelabelofaele-ment.
watermark-imageURI.
IftheURIisrela-tive,itisrelativetothecurrentworkingdirecto-ryoftheuser.
Nodefaultvalue.
Specifiesanimagefilewhichistobeusedasawa-termarkinallthepagescomprisingtheoutputdoc-ument.
Seealsoparameterwatermark.
IfyouneedthisfeaturewhengeneratingRTF,WordprocessingML,OfficeOpenXML(.
docx),OpenDocument(.
odt),pleasemakesuretouseXMLmindXSL-FOConverterv5.
3+.
Chapter4.
XSLTstylesheetsparameters26XMLmindDITAConverterManualParameterValueDescriptionxref-auto-textListofvaluesseparatedbywhitespace.
Allowedvaluesare:'number'and'text'.
Defaultvalue:'num-ber'.
Thisparameterspecifieswhichtexttogenerateforanelement,whenthiselementcontainsnotextatall(5).
Let'ssupposethatanelementcontainingnotextatallpointstoatopictitled"Installa-tion".
Becausetheelementpointstoanelementhavingachildelement,ditacmayusethistitleasastartingpointforthegeneratedtext.
Nowlet'ssupposethattopicsarenumberedandthatthenumberofthe"Installation"topicis"Chapter5".
Thetextgeneratedforthiselementisthus:Ifxref-auto-text='number'Chapter5Ifxref-auto-text='text'InstallationIfxref-auto-text='numbertext'Chapter5.
InstallationNotethatthisspecificationisjustahintbecauseditacneedsanywaytogeneratesometext.
Forex-ample,iftopicsarenotnumberedandxref-au-to-text='number',thegeneratedtextwillbe"Installation".
xsl-re-sources-directoryURL.
ArelativeURLisrelativetotheoutputdi-rectory.
Defaultvalue:'re-sources/'resolvedagainstthedirecto-rywhichcontainstheXSLTstylesheets.
MostXSLTstylesheetsgeneratefileswhichrefer-enceresourcessuchasiconsorCSSstylesheets.
Thisparameterspecifiesthetargetdirectorywhichistocontainsuchresources.
Ifthisdirectorydoesnotexist,itisautomaticallycreated.
Ifthisdirectorydoesnotalreadycontainthere-sourcesneededbytheXSLTstylesheets,suchre-sourcesareautomaticallycopiedtothisdirectory.
Thedefaultvalueofthisparameterissome-thinglikefile:/opt/ditac/xsl/xhtml/re-sources/forthestylesheetsgeneratingXHTML.
URLfile:/opt/ditac/xsl/xhtml/re-sources/specifiesanexistingdirectorycontain-ingbasic.
css,note.
png,important.
png,etc.
Thismeansthatbydefault,nodirectoryiscreatedandnoresourceiscopied.
(5)Thisimpliesthatthexref-auto-textparameterisignoredwhenanelementcontainssometext.
Chapter4.
XSLTstylesheetsparameters27XMLmindDITAConverterManualParameterValueDescriptionIfthevalueofthisparameterisanabsoluteURI,thenditacassumesthatnoresourcedirectoryistobecreatedandnoresourceistobecopiedbecausethishasalreadybeendonebytheuser.
ImportantExplicitlyspecifyingsomethinglikexsl-resources-direc-tory='res'isalmostalwaysrequiredwhengeneratingfileshav-inganXHTML/HTMLbasedformat(XHTML,HTMLHelp,etc).
Explicitlyspecifyingsomethinglikexsl-resources-direc-tory='res'isalmostneverrequiredwhengeneratingfilescon-vertedfromXSL-FO(PDF,RTF,etc).
ParameterscommontothestylesheetsthatbasicallygenerateXHTMLorHTMLThisappliestothestylesheetsthatgenerateXHTML,HTML,WebHelp,JavaHelp,HTMLHelp,EclipseHelp,EPUB.
ParameterValueDescriptionadd-index-tocAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
SpecifieswhetheranA-Zlistshouldbeaddedatthebeginningoftheback-of-the-bookindex.
chain-pagesAllowedvaluesare:'none','top','bot-tom'or'both'.
Defaultvalue:'none'.
Specifieswhetheraheaderand/orafootercontain-ingnavigationiconsshouldbegeneratedinordertolinktogetheralltheHTMLpages.
NoteThereisnoneedtospecifyavalueotherthan'none'whengeneratingWebHelp,Chapter4.
XSLTstylesheetsparameters28XMLmindDITAConverterManualParameterValueDescriptionHTMLHelp,EclipseHelp,EPUBandJavaHelp.
chain-topicsAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhethernavigationiconsshouldbegen-eratedinordertolinktogetherallthetopics.
Seealsorelatedparameter:ignore-naviga-tion-links.
NoteThereisnoneedtospeci-fyavalueotherthan'no'whengeneratingWebHelp,HTMLHelp,EclipseHelp,EPUBandJavaHelp.
cssURL.
Defaultvalue:''.
Low-levelparameterspecifyingwhichCSSstylesheettousetostylethegenerated(X)HTMLpages.
Whenneithercssnorcustom-cssisspecified,thedefaultCSSstylesheetbeingusedisxsl-re-sources-directory/base.
css.
RestrictionNotsupportedbythestylesheetsthatgenerateEPUB.
cssResourceNameURLbasenamerelativetothedirectoryspecifiedbyparameterxsl-re-sources-directory.
Defaultvalue:'base.
css'.
Verylow-levelparameterspecifyingwhichCSSstylesheettouse.
ThisCSSstylesheetisexpectedtobefoundintheresourcesdirectory.
NoteThisparameterisnotusefulunlessyoudevelopaplug-inimplementingaDITAspe-cialization.
Moreinforma-tioninPartII,Chapter10.
custom-cssURL.
Defaultvalue:''.
SpecifiesthecustomCSSstylesheetusedtostylethegenerated(X)HTMLpages.
Thishigh-levelpa-rameterhaspriorityoverlow-levelparametercss.
Chapter4.
XSLTstylesheetsparameters29XMLmindDITAConverterManualParameterValueDescriptionThiscustomCSSstylesheetiscopiedtodirecto-ryxsl-resources-directory.
Thereforecus-tom-cssrequiresdirectoryxsl-resources-di-rectorytobespecifiedasanURLwhichisrelativetotheoutputdirectory(e.
g.
xsl-re-sources-directory='res').
Howtousecustom-cssisexplainedinPartII,Chapter9,Section1.
default-ta-ble-widthApercentage,typicallysomethinglike'100%'or'90%'.
Defaultvalue:''(asnarrowaspossible).
Thedefaultwidthofandelements.
external-link-icon-heightLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'10'.
Theheightofthe"opensinnewwindow"icon.
external-link-icon-nameBasename.
Defaultvalue:'new_window.
png'.
Thebasenameofthe"opensinnewwindow"icon.
Thisiconisfoundintheresourcesdirectory.
external-link-icon-widthLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'10'.
Thewidthofthe"opensinnewwindow"'icon.
format-to-typeZeroormoreDITAfor-mat/MIMEtypepairs.
Example:"txttext/plainxmlappli-cation/xmlhtml-text/html".
Defaultvalue:'',whichmeansthatDITAxref/@formatisnotcon-vertedtoXHTMLa/@type.
AllowstomapDITAxref/@formattoXHTMLa/@type.
Usingdefaultemptyvalue,isconvert-edto.
Thefactthatfileextension".
xyz"isunknownmaycauseproblemswhenat-temptingtonavigateordownloadfile"info.
xyz"usingaWebbrowser.
If-pformat-to-type"txttext/plain"ispassedtoditactheniscon-vertedto,whichisbetter.
generator-infoStringThenameofthesoftwarewhichhasbeenusedtocreatetheHTMLpages.
Chapter4.
XSLTstylesheetsparameters30XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'XML-mindDITAConvert-erVERSION'.
Specifyanemptystringifyoudon'twanttohaveaelementaddedtoyourHTMLpages.
ignore-naviga-tion-linksAllowedvaluesare:'yes','no'and'au-to'.
Defaultvalue:'au-to'forXHTMLanditsvariants;'yes'forWebHelp,JavaHelp,HTMLHelp,EclipseHelpandEPUBIf'yes',donotgeneratethenavigationlinkscorrespondingtotopicrefattribute@collec-tion-type.
If'no',generatethenavigationlinkscorrespond-ingtotopicrefattribute@collection-type.
If'auto',generatethenavigationlinkscor-respondingtotopicrefattribute@collec-tion-type,unlesschain-topics=yes.
javascriptsString.
ListofURLsseparatedbywhitespace.
Defaultvalue:''.
TheURLsspecifiedinthisparametermustpointtoJavaScriptfiles.
TheseURLsareconvertedtoXHTMLelementsaddedtothe/elementsoftheXHTMLfilesgeneratedbyditac.
NotethatanURLmayendwith';async',';de-fer'oracombinationofbothflags.
Theseflagsaretranslatedtothecorrespondingattributesoftheelement.
Example:https://cdnjs.
cloudflare.
com/ajax/libs/mathjax/2.
7.
7/MathJax.
jsconfig=MML_CHTML;asyncistranslatedto:mathjaxAllowedvaluesare:'yes','no'and'au-to'.
Defaultvalue:'no'.
Veryfewwebbrowsers(Firefox)cannativelyren-derMathML.
Fortunately,thereisMathJax.
Math-JaxisaJavaScriptdisplayengineformathematicsthatworksinallbrowsers.
'yes'AddaXHTMLelementload-ingMathJaxtothe/ele-mentsofallXHTMLfilesgeneratedbyditac.
'auto'Sameas'yes',butaddon-lytogeneratedXHTMLfilescontainingMathML.
IgnoredbyallXHTML-basedformatsbutXHTMLandWebHelp.
mathjax-urlString.
TheURLallowingtoloadtheMathJaxengineconfiguredforrenderingMathML.
Chapter4.
XSLTstylesheetsparameters31XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:theURLpointingtotheMathJaxCDN,asrecommend-edintheMathJaxdocu-mentation.
Ignoredunlessparametermathjaxissetto'yes'or'auto'.
mark-exter-nal-linksAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetheranexternallinkshouldbemarkedusinga"opensinnewwindow"icon.
navigation-icon-heightLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'16'.
Theheightofanavigationicon.
navigation-icon-suffixString.
Defaultvalue:'.
png'.
Thesuffixofanavigationicon.
Therootnamesofnavigationiconsarefixed:first,first_disabled,last,last_disabled,next,next_disabled,previous,previous_disabled,parent,parent_disabled,child,child_disabled.
Forexample,ifnote-icon-suffix='.
svg',thedefaultresourcesdirectoryisexpectedtocontainfirst.
svg,first_disabled.
svg,last.
svg,etc.
Inprinciple,thereisnoneedforanend-usertospecifyanyofthenavigation-icon-suf-fix,navigation-icon-widthornaviga-tion-icon-heightparameters.
navigation-icon-widthLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'16'.
Thewidthofanavigationicon.
screen-resolutionPositiveinteger.
Defaultvalue:'96'.
Theresolutionofthescreenindotperinch(DPI).
Thisresolutionisusedtoconvertimagedimen-sionssuchas3cmtopixels.
xhtml-mime-typeAMIMEtypewith-outaparametersuchas'text/html','ap-plication/xhtml+xml','applica-tion/xml'ortheemp-tystring('').
Defaultvalue:seeprose.
Low-levelparameter.
Donotchangedefaultvalueunlessyouknowwhatyouaredoing.
Specify'text/html'toserveXHTMLasHTML.
Thisisthedefaultvalueforall(X)HTML-basedoutputformatsexceptforEPUB2and(X)HTML5.
Chapter4.
XSLTstylesheetsparameters32XMLmindDITAConverterManualParameterValueDescriptionSpecify'application/xhtml+xml'ifyouprefertoserveXHTMLasXML.
ThisisthedefaultvalueforEPUB2.
Specifyanemptystringifyouprefernottogenerate.
Thisisthedefaultvaluefor(X)HTML5forwhichaisgen-eratedinstead.
ParameterscommontothestylesheetsthatgenerateWebHelp,JavaHelp,HTMLHelp,EclipseHelpandEPUBParameterValueDescriptionadd-toc-rootAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
If'yes',addapseudoTOCentry,bearingtheti-tleofthedocument,containingalltheactualTOCentries.
RestrictionValue'no'isnotsupportedbythestylesheetsthatgener-ateEclipseHelp.
Ignoredbythestylesheetsthatgen-erateWebHelpandEPUB.
number-toc-entriesAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'forWebHelp,'no'fortheotherformats.
If'yes',numbertheTOCentries.
Noeffectun-lessthenumberparameterisusedtospecifythattopicsshouldbenumbered.
ParametersspecifictothestylesheetsthatgenerateWebHelpParameterValueDescriptionwh---CSS_VAR_NAMEString.
AvalidCSSpropertyvalue.
Nodefault.
ThiskindofparametermaybeusedtooverrideanyofthedefaultvaluesoftheCSSvariablesspec-ifiedinanyoftheNNtheme.
csstemplatefiles(allfoundinditac_install_dir/whc_tem-plate/_wh/).
Forexample,themainNNtheme.
csstemplatefile:Chapter4.
XSLTstylesheetsparameters33XMLmindDITAConverterManualParameterValueDescriptionbody{.
.
.
--navigation-width:33%;.
.
.
}Thewh---navigation-widthCSSvariableisusedasfollowsinNNcommon.
css,anotherCSStemplatefile:#wh-navigation{.
.
.
width:var(--navigation-width);.
.
.
}Thereforeparameterwh---navigation-widthmaybeusedtogivethenavigationsideofthegen-eratedWebHelpadifferentinitialwidth.
Example:-pwh---navigation-width"25%".
Moreexamplesin"XMLmindWebHelpCompilerManual,Gettingstarted".
wh-collapse-tocAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
SpecifieswhethertheTOCshouldbeinitiallycol-lapsed.
wh-index-numbersAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetherwordslookinglikenumbersaretobeindexed.
Examplesofsuchnumber-likewords:3.
14,3,14,3times4equals12,+1,-1.
0,3px,1,2cm,100%,1.
0E+6,1,000.
00$.
wh-inherit-font-and-colorsAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Whenwh-inherit-font-and-colorsissetto'no',thenavigationpaneofthegeneratedWebHelpusesfontsandcolorsofitsown,whichwillgenerallydifferfromthoseusedforthecontentoftheWebHelp.
Settingwh-inherit-font-and-colorsto'yes'letsyouuseforthenavigationpanethesamefontsandcolorsasthoseusedforthecontentoftheWebHelp.
Sobasicallythisparameterisashorthandfor:-pwh---navigation-font-familyinherit-pwh---navigation-font-sizeinherit-pwh---navigation-colorinherit-pwh---navigation-background-colorinheritSeeabovewh---CSS_VAR_NAMEparameters.
Chapter4.
XSLTstylesheetsparameters34XMLmindDITAConverterManualParameterValueDescriptionwh-jqueryRelativeorabsoluteURI.
ArelativeURIisrelativetotheURIofapageoftheWebHelp.
Defaultvalue:absoluteURIofthecorrespond-ingfilefoundontheGoogleCDN.
SpecifiesthelocationoftheJavaScriptfilecon-tainingjQuery.
Example:https://code.
jquery.
com/jquery-3.
4.
1.
slim.
min.
jsSpecifyingan"https:"URLisrecommend-edwhenthegeneratedWebHelpisstoredonanHTTPSserver.
wh-local-jqueryAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
SpecifieswhetheralljQueryfilesshouldbecopiedto_wh/jquery/,where_wh/isthedirectorycon-tainingtheotherWebHelpfiles.
Bydefault,thejQueryfilesareaccessedfromtheWeb(typicallyfromaCDN).
NotethatthisparameterisappliedafterjQueryhasbeenpossiblycustomizedus-ingparameterwh-jquery.
Forexample,"-pwh-jqueryhttps://code.
j-query.
com/jquery-3.
4.
1.
js"copiesafiledownloadedfromhttps://code.
jquery.
com/to_wh/jquery/.
wh-layoutThenameofalayout.
Defaultvalue:classic.
SelectsalayoutforthegeneratedWebHelp.
Fornow,onlytwolayoutsaresupported:classicandsimple.
wh-responsive-uiAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
SpecifieswhetherthegeneratedWebHelpshouldbe"responsive",thatis,whetheritshouldadaptitslayouttothesizeofthescreen.
wh-ui-language"browser"or"doc-ument"oralanguagecodeconformingRFC3066.
Examples:de,fr-CA.
Defaultvalue:'brows-er'.
Specifieswhichlanguageshouldbeusedforthemessages(tablabels,buttontooltips,etc)ofthegeneratedWebHelp.
Defaultvalue"browser"meansthatthislanguageistheoneusedbytheWebbrowserforitsownmessages.
ThislanguagemayoftenbespecifiedintheuserpreferencesoftheWebbrowser.
Value"document"meansthatthelanguageofthedocumentshouldbeused.
Alanguagecodesuchasen,en-US,es,es-AR,etc,maybeusedtoexplicitlyspecifywhichlan-guageshouldbeused.
Chapter4.
XSLTstylesheetsparameters35XMLmindDITAConverterManualParameterValueDescriptionwh-use-stemmingAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Specifieswhetherstemming(6)shouldbeusedtoimplementthesearchfacility.
Bydefault,stem-mingisusedwheneverpossible,thatis,1.
whenthemainlanguageofthedocumentcanbedetermined;2.
whenthismainlanguageisoneof:Danish,Dutch,English,Finnish,French,German,Hungarian,Italian,Norwegian,Portuguese,Russian,Spanish,Swedish,Romanian,Turk-ish.
Themainlanguageofthedocumentisspecifiedbythe@xml:langattributefoundontherootele-mentofDITAmapbeingconverted;otherwiseus-ingthe-langcommand-lineoption;otherwise,itisassumedtobe"en".
wh-user-cssFilenameorabsoluteURIofaCSSfile.
Arel-ativefilenameisrelativetothecurrentworkingdirectory.
Specifiestheuser'sCSSstylesheetwhichistobeaddedtoeachpageoftheWebHelp.
Thisfileiscopiedtooutput_directory/_wh/user/.
Sampleuser'sCSSwh_resources/header_footer.
cssasusedinthefollowingexample:-pwh-user-headerwh_resources/header.
html-pwh-user-footerwh_resources/footer.
html-pwh-user-csswh_resources/header_footer.
css-pwh-user-resourceswh_resources/header_footer_fileswh-user-footerFilenameorabsoluteURIofanXHTMLfile.
Arelativefilenameisrelativetothecurrentworkingdirectory.
Specifiestheuser'sfooterwhichistobeaddedtoeachpageoftheWebHelp.
Thecontentoftheelementofwh-user-footerisinsertedasisinthefoundineachpageoftheWebHelp.
Sameremarkasforparameterwh-user-headerabouttheresourcesreferencedbyauser'sfooter.
Sampleuser'sfooterwh_resources/footer.
htmlasusedinthefollowingexample:-pwh-user-headerwh_resources/header.
html-pwh-user-footer(6)Inlinguisticmorphologyandinformationretrieval,stemmingistheprocessofreducinginflected(orsometimesde-rived)wordstotheirwordstem,baseorrootform—generallyawrittenwordform.
Chapter4.
XSLTstylesheetsparameters36XMLmindDITAConverterManualParameterValueDescriptionwh_resources/footer.
html-pwh-user-csswh_resources/header_footer.
css-pwh-user-resourceswh_resources/header_footer_filesMoreexamplesin"XMLmindWebHelpCompilerManual,Gettingstarted".
wh-user-headerFilenameorabsoluteURIofanXHTMLfile.
Arelativefilenameisrelativetothecurrentworkingdirectory.
Specifiestheuser'sheaderwhichistobeaddedtoeachpageoftheWebHelp.
Thecontentoftheelementofwh-user-headerisinsertedasisinthefoundineachpageoftheWebHelp.
Ifauser'sheaderreferencesresources(e.
g.
imagefiles),thentheseresourcesmusteitherberefer-encedusingabsoluteURLsortheseresourcesmustbefoundinauser'sresourcedirectoryandparame-terwh-user-resourcesmustbespecified.
Example:Theuser'sresourcedirectoryiscalledhead-er_footer_files/andcontainshead-er_footer_files/200x100.
png.
ditacispassedparameters:-pwh-user-resourcesPATH_TO/header_foot-er_filesand-pwh-user-header-PATH_TO/header.
html.
header.
htmllookslikethis:.
.
.
.
.
.
.
.
.
Noticethepathusedtoreferencelo-go200x100.
png.
Sampleuser'sheaderwh_resources/header.
htmlasusedinthefollowingexample:-pwh-user-headerwh_resources/header.
html-pwh-user-footerwh_resources/footer.
htmlChapter4.
XSLTstylesheetsparameters37XMLmindDITAConverterManualParameterValueDescription-pwh-user-csswh_resources/header_footer.
css-pwh-user-resourceswh_resources/header_footer_filesMoreexamplesin"XMLmindWebHelpCompilerManual,Gettingstarted".
wh-user-re-sourcesFilenameorabsolute"file:"URIofadi-rectory.
URIschemesotherthan"file"(e.
g.
"http")arenotsupport-edforthisparameter.
Arelativefilenameisrela-tivetothecurrentwork-ingdirectory.
Specifiesauser'sresourcedirectorywhichistoberecursivelycopiedtooutput_directory/_wh/user/.
Thisdirectorytypicallycontainsimagefilesreferencedbytheuser'sheader,footerorCSSstylesheet.
Sampleuser'sresourcedirectorywh_re-sources/header_footer_files/asusedinthefollow-ingexample:-pwh-user-headerwh_resources/header.
html-pwh-user-footerwh_resources/footer.
html-pwh-user-csswh_resources/header_footer.
css-pwh-user-resourceswh_resources/header_footer_filesMoreexamplesin"XMLmindWebHelpCompilerManual,Gettingstarted".
whc-index-basenameURLbasename.
Defaultvalue:'whc_index.
xml'.
BasenameoftheIndexXMLinputfileofXML-mindWebHelpCompiler.
Inprinciple,thereisnoneedforanend-usertospecifythisparameter.
whc-toc-basenameURLbasename.
Defaultvalue:'whc_toc.
xml'.
BasenameoftheTOCXMLinputfileofXML-mindWebHelpCompiler.
Inprinciple,thereisnoneedforanend-usertospecifythisparameter.
ParametersspecifictothestylesheetsthatgenerateJavaHelpInprinciple,thereisnoneedforanend-usertospecifyanyofthefollowingparameters.
ParameterValueDescriptionhelpset-basenameURLbasename.
Defaultvalue:'jhelpset.
hs'.
BasenameoftheJavaHelpHelpSetfile.
index-basenameURLbasename.
BasenameoftheJavaHelpIndexfile.
Chapter4.
XSLTstylesheetsparameters38XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'jhelpidx.
xml'.
indexer-directo-ry-basenameURLbasename.
Defaultvalue:'Java-HelpSearch'.
Basenameofthedirectorywhichwillcontainthedatageneratedbyrunningjhindexer.
AproperlyquotedrelativeURL,notafilename.
map-basenameURLbasename.
Defaultvalue:'jhelpmap.
jhm'.
BasenameoftheJavaHelpMapfile.
toc-basenameURLbasename.
Defaultvalue:'jhelp-toc.
xml'.
BasenameoftheJavaHelpContentsfile.
ParametersspecifictothestylesheetsthatgenerateHTMLHelpInprinciple,thereisnoneedforanend-usertospecifyanyofthefollowingparameters.
ParameterValueDescriptionchmBasenameURLbasename.
Defaultvalue:'help.
chm'.
BasenameofthecompiledHTMLHelpfile.
hhc-basenameURLbasename.
Defaultvalue:'toc.
h-hc'.
BasenameoftheHTMLHelpcontentsfile.
hhp-templateURLbasename.
Defaultvalue:'tem-plate.
hhp'resolvedagainstthedirecto-rywhichcontainstheXSLTstylesheets.
URLofthefilecontainingthetemplateoftheHTMLHelpprojectfile.
Thisplaintextfileen-codedinUTF-8containsvariablessuchas%com-piledFile%,%contentsFile%,%default-Topic%,etc,whicharesubstitutedwiththeirval-ues.
hhpBasenameURLbasename.
Defaultvalue:'project.
hhp'.
BasenameoftheHTMLHelpprojectfile.
hhx-basenameURLbasename.
Defaultvalue:'in-dex.
hhx'.
BasenameoftheHTMLHelpindexfile.
ParametersspecifictothestylesheetsthatgenerateEclipseHelpParameterValueDescriptionplugin-idStringNodefaultvalue.
AnIDuniquelyidentifyingtheplug-in,typical-lyaJava-likefullyqualifiedname.
Example:'com.
acme.
widget.
userguide'.
Chapter4.
XSLTstylesheetsparameters39XMLmindDITAConverterManualParameterValueDescriptionImportantThesubdirectoryofplug-ins/containingtheplug-inmusthavethesamebase-nameasthevalueofpara-meterplugin-id.
plugin-index-base-nameURLbasename.
Defaultvalue:'in-dex.
xml'.
Basenameoftheindexfile.
plugin-nameStringNodefaultvalue.
Thenameoftheplug-in,typicallythetitleofthedocument.
Example:'ACMEWidgetUser&a-pos;sGuide'.
plugin-providerStringNodefaultvalue.
Theauthor,companyororganizationwhichhascontributedtheplug-in.
Example:'ACMECorp.
'.
plugin-toc-base-nameURLbasename.
Defaultvalue:'toc.
xml'.
Basenameofthetableofcontentsfile.
plugin-versionStringDefaultvalue:'1.
0.
0'.
Theversionoftheplug-in.
ParametersspecifictothestylesheetsthatgenerateEPUBParameterValueDescriptioncover-imageURI.
IftheURIisrela-tive,itisrelativetothecurrentworkingdirecto-ryoftheuser.
Nodefaultvalue.
SpecifiesanimagefilewhichistobeusedasthecoverpageoftheEPUBfile.
ThisimagemustbeaPNGorJPEGimage.
Itssizemustnotexceed1000x1000pixels.
Intheory,EPUB3alsoacceptsSVG1.
1coverim-ages.
epub-identifierStringDefaultvalue:dynam-icallygeneratedUUIDURN.
AgloballyuniqueidentifierforthegeneratedEPUBdocument(typicallythepermanentURLoftheEPUBdocument).
epub2-compatibleAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
OnlyappliestoEPUB3.
Bydefault,theEPUB3filesgeneratedbyditacaremadecompatiblewithEPUB2readers.
Specify'no'ifyoudon'tneedthiscompatibility.
Chapter4.
XSLTstylesheetsparameters40XMLmindDITAConverterManualParameterValueDescriptiongenerate-epub-triggerAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
OnlyappliestoEPUB3.
Specify'no'ifyourEPUB3readerdoesnotsup-portepub:triggeryet.
Whengenerate-epub-trigger=no,ditacgeneratesan@onclickat-tributecontainingsimpleJavaScriptcodeandde-claresthecontainingXHTML5pageasbeingscripted.
ParametersspecifictothestylesheetsthatgenerateXSL-FOTheXSL-FOfilegeneratedbytheXSLTstylesheetsisconvertedtoPDF,PostScript,RTF,Wordprocess-ingML,OfficeOpenXML(.
docx),OpenOffice/LibreOffice(.
odt)bythemeansofXSL-FOprocessorssuchasApacheFOP,RenderXXEP,AntennaHouseXSLFormatterorXMLmindXSL-FOConverter.
TipInsertingaprocessing-instructioninthetopicsourcebetweenparagraphs,notes,tables,lists,etc,maybeusedtoforceapagebreakwhengeneratinganyoftheoutputformatswhichusesXSL-FOasanintermediateformat(PDF,RTF,DOCX,etc).
ParameterValueDescriptionbase-font-sizeDefaultvalue:'10pt'.
Thesizeofthe``mainfont''ofthedocument.
Alltheotherfontsizesarecomputedrelativelytothisfontsizebody-bot-tom-marginLength.
Defaultvalue:'0.
5in'.
SeeFigure4-1below.
body-font-fam-ilyAstringcontainingoneormorefontfamiliesseparatedbycommas.
Defaultvalue:'serif'.
Specifiesthefamilyofthefontusedforthetextofallele-mentsexcepttopictitles.
body-start-in-dentLength.
Defaultvalue:'2pc'.
AppliesonlytoalternateXSLTstylesheetditac_instal-l_dir/xsl/fo/fo_indent.
xsl.
Thisstylesheet:Indentsallblocksbuttopicandsectiontitlesbytheval-ueofXSLTstylesheetparameterbody-start-indent.
Bydefaultbody-start-indentis2pc.
Addsmoreverticalspaceaftertopicandsectiontitles.
Onlypart,appendices,chapterandappendixtitlesareunderlined.
Chapter4.
XSLTstylesheetsparameters41XMLmindDITAConverterManualParameterValueDescriptionThisstylesheetisinvokedbypassingoption-tditac-xs-l:fo/fo_indent.
xsltoditac.
Exampleofitsoutput:manual-fop.
pdf.
body-top-mar-ginLength.
Defaultvalue:'0.
5in'.
SeeFigure4-1below.
choice-bulletsAstringcontainingoneormoresinglecharactersseparat-edbywhitespace.
Defaultvalue:'•'(BUL-LET).
Specifywhichbulletcharactertouseforaele-ment.
Additionalcharactersareusedfornestedel-ements.
Changingthevalueofthisparametermayimplychangingthefont-familyattributeoftheattribute-setchoice-label.
equa-tion-block-equation-widthLength.
Defaultvalue:'90%'.
Inanumberedelement,thisparameterspecifiesthewidthofthecolumncontainingtheequation.
equa-tion-block-number-widthLength.
Defaultvalue:'10%'.
Inanumberedelement,thisparame-terspecifiesthewidthofthecolumncontainingtheelement.
external-href-afterString.
Defaultvalue:']'.
AppendedaftertheexternalURLreferencedbyanorelement.
Ignoredunlessshow-exter-nal-links='yes'.
external-href-beforeString.
Defaultvalue:'['.
SeparatesthetextofanorelementfromitsreferencedexternalURL.
Ignoredunlessshow-exter-nal-links='yes'.
foProcessorString.
Examples:'FOP','XEP','AHF','XFC'.
Defaultvalue:''.
ThenameoftheXSL-FOprocessorusedtoconverttheXSL-FOfilegeneratedbytheXSLTstylesheetstothetargetoutputformat.
footer-centerString.
Specifiesthecontentsofthecentralpartofapagefooter.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
Defaultvalue:two-sideseven::{{chapter-title}};;two-sidespart||chapter||appendices||appendixodd::{{section1-title}};;one-side::{{chapter-title}}footer-cen-ter-widthStringrepresentinganintegerlargerthanorequalto1.
Specifiestheproportionalwidthofthecentralpartofapagefooter.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
Chapter4.
XSLTstylesheetsparameters42XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'6'.
footer-heightLength.
Defaultvalue:'0.
4in'.
SeeFigure4-1below.
footer-leftString.
Specifiesthecontentsoftheleftpartofapagefooter.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
Defaultvalue:two-sideseven::{{page-number}}footer-left-widthStringrepresentinganintegerlargerthanorequalto1.
Defaultvalue:'2'.
Specifiestheproportionalwidthoftheleftpartofapagefoot-er.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
footer-rightString.
Specifiesthecontentsoftherightpartofapagefooter.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
Defaultvalue:two-sidesfirst||odd::{{page-number}};;one-side::{{page-number}}footer-right-widthStringrepresentinganintegerlargerthanorequalto1.
Defaultvalue:'2'.
Specifiestheproportionalwidthoftherightpartofapagefooter.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
footer-separa-torAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Specifieswhetheranhorizontalruleshouldbedrawnabovethepagefooter.
header-centerString.
Defaultval-ue:'{{docu-ment-title}}'.
Specifiesthecontentsofthecentralpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-cen-ter-widthStringrepresentinganintegerlargerthanorequalto1.
Defaultvalue:'6'.
Specifiestheproportionalwidthofthecentralpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-heightLength.
SeeFigure4-1below.
Chapter4.
XSLTstylesheetsparameters43XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'0.
4in'.
header-leftString.
Defaultvalue:''.
Specifiesthecontentsoftheleftpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-left-widthStringrepresentinganintegerlargerthanorequalto1.
Defaultvalue:'2'.
Specifiestheproportionalwidthoftheleftpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-rightString.
Defaultvalue:''.
Specifiesthecontentsoftherightpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-right-widthStringrepresentinganintegerlargerthanorequalto1.
Defaultvalue:'2'.
Specifiestheproportionalwidthoftherightpartofapageheader.
SeeSpecifyingaheaderorafooter.
Supportsaconditionalspecification.
header-separa-torAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Specifieswhetheranhorizontalruleshouldbedrawnbelowthepageheader.
hyphenateAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetherwordsmaybehyphenated.
index-col-umn-countPositiveinteger.
Defaultvalue:'2'.
Thenumberofcolumnsofindexpages.
index-col-umn-gapLength.
Defaultvalue:'2em'.
Thedistancewhichseparatescolumnsinindexpages.
justifiedAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhethertext(e.
g.
inparagraphs)shouldbejustified(thatis,flushleftandright)orjustleftaligned(thatis,flushleftandraggedright).
link-bulletAstringcontainingasinglecharacter.
Specifywhichcharacterisinsertedbeforethetextofaelement.
Changingthevalueofthisparametermayimplychangingthefont-familyattributeoftheattribute-setlink-bullet.
Chapter4.
XSLTstylesheetsparameters44XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'•'(BUL-LET).
menucas-cade-separatorAstringcontainingasinglecharacter.
Defaultvalue:'→'(RIGHTWARDSARROW).
Specifywhichcharacterisusedtoseparatethechildelementsofaelement.
Changingthevalueofthisparametermayimplychangingthefont-familyattributeoftheattribute-setmenucas-cade-separator.
note-icon-heightLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'32'.
'7mm'fortheXSLTstylesheetsthatgenerateXSL-FO.
Theheightofanoteicon.
note-icon-suf-fixDefaultvalue:'.
png'.
Thesuffixofanoteicon.
Therootnameofanoteiconshouldbeidenticaltotheval-ueofthe@typeattributeitrepresents.
Forexample,ifnote-icon-suffix='.
svg',thedefaultresourcesdirectoryisexpectedtocontainnote.
svg,important.
svg,cau-tion.
svg,etc.
Inprinciple,thereisnoneedforanend-usertospecifyanyofthenote-icon-suffix,note-icon-widthornote-icon-heightparameters.
note-icon-widthLength.
Alengthmayhaveaunit.
Defaultispx.
Defaultvalue:'32'.
'7mm'fortheXSLTstylesheetsthatgenerateXSL-FO.
Thewidthofanoteicon.
page-bot-tom-marginLength.
Defaultvalue:'0.
5in'.
SeeFigure4-1below.
page-heightLength.
Example:'297mm'.
Defaultvalue:dependsonpa-per-type.
Theheightoftheprintedpage.
Chapter4.
XSLTstylesheetsparameters45XMLmindDITAConverterManualParameterValueDescriptionpage-in-ner-marginLength.
Defaultvalue:ifparametertwo-sidedisspeci-fiedas'yes'then'1.
25in'other-wise'1in'.
SeeFigure4-1below.
page-orienta-tionAllowedvaluesare:'portrait'and'land-scape'.
Defaultvalue:'portrait'.
Theorientationoftheprintedpage.
page-out-er-marginLength.
Defaultvalue:ifparametertwo-sidedisspeci-fiedas'yes'then'0.
75in'other-wise'1in'.
SeeFigure4-1below.
page-ref-afterString.
Defaultvalue:''.
Appendedafterthepagenumberpointedtobyanorelement.
Ignoredunlessshow-xref-page='yes'orshow-link-page='yes'.
Whenbothpage-ref-afterandpage-ref-beforearespecifiedastheemptystring,infact,thisspecifiesthatthegeneratedstringmustbethelocalizedequivalentof"onpage".
page-ref-be-foreString.
Defaultvalue:''.
Separatesthetextofanorelementfromthepagenumberitpointsto.
Ignoredunlessshow-xref-page='yes'orshow-link-page='yes'.
page-top-mar-ginLength.
Defaultvalue:'0.
5in'.
SeeFigure4-1below.
page-widthLength.
Example:'8.
5in'.
Defaultvalue:dependsonpa-per-type.
Thewidthoftheprintedpage.
paper-typeAllowedval-uesare:'Let-ter','Le-gal','Ledger','Tabloid','A0',Aconvenientwaytospecifythesizeoftheprintedpage.
Itisalsopossibletospecifyacustompapertypebyignoringthepaper-typeparameteranddirectlyspecifyingthepage-widthandpage-heightparameters.
Chapter4.
XSLTstylesheetsparameters46XMLmindDITAConverterManualParameterValueDescription'A1','A2','A3','A4','A5','A6','A7','A8','A9','A10','B0','B1','B2','B3','B4','B5','B6','B7','B8','B9','B10','C0','C1','C2','C3','C4','C5','C6','C7','C8','C9','C10'(case-insen-sitive).
Defaultvalue:'A4'.
pdf-outlineAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
SpecifieswhetherPDFbookmarksshouldbegenerated.
Supportedbythe'XEP','FOP'and'AHF'XSL-FOproces-sors.
Notrelevant,andthusignoredby'XFC'.
show-exter-nal-linksAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
SpecifieswhethertheexternalURLreferencedbyanorelementshouldbedisplayedrightafterthetextcontainedbythiselement.
Example:show-external-links='yes'causesOasistoberenderedasfollows:Oasis[http://www.
oa-sis-open.
org/].
show-im-agemap-linksAllowedvaluesare:'yes'and'no'.
Defaultvalue:'yes'.
Specifieswhetheranumberedlistshouldbegeneratedforanelement,withonelistitemperele-ment.
Alistitemcontainsthelinkspecifiedbytheelement.
Nolistitemsaregeneratedfor"deadareas"(ele-mentsspecifyingnolinkatall).
show-link-pageAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Sameasshow-xref-pagebutforelements.
show-xref-pageAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetherthepagenumbercorrespondingtothein-ternallinktargetreferencedbyanelementshouldbedisplayedrightafterthetextcontainedbythiselement.
Example:show-xref-page='yes'causesIntroductiontoberenderedasfollows:Introduction[3].
Chapter4.
XSLTstylesheetsparameters47XMLmindDITAConverterManualParameterValueDescriptiontitle-colorAstringrepresent-ingacolor.
Defaultvalue:'black'.
Specifiesthecolorusedforthetextoftopic(ofanykind)ti-tles.
title-font-familyAstringcontainingoneormorefontfamiliesseparatedbycommas.
Defaultvalue:'sans-serif'.
Specifiesthefamilyofthefontusedforthetextoftopic(ofanykind)titles.
two-sidedAllowedvaluesare:'yes'and'no'.
Defaultvalue:'no'.
Specifieswhetherthedocumentshouldbeprinteddoublesided.
ul-li-bulletsAstringcontainingoneormoresinglecharactersseparat-edbywhitespace.
Defaultvalue:'•–'(BUL-LET,ENDASH).
Specifywhichbulletcharactertouseforan/el-ement.
Additionalcharactersareusedfornestedele-ments.
Forexample,iful-li-bullets=willbeusedfor/elements,"-"willbeusedfor/elementscontainedina/elementand"+"willbeusedfor/elementsnestedintwo/elements.
Changingthevalueofthisparametermayimplychangingthefont-familyattributeoftheattribute-setul-li-label.
un-ordered-step-bulletsAstringcontainingoneormoresinglecharactersseparat-edbywhitespace.
Defaultvalue:'•'(BUL-LET,ENDASH).
Specifywhichbulletcharactertousefora/element.
Additionalcharactersareusedfornested/elements.
Changingthevalueofthisparametermayimplychang-ingthefont-familyattributeoftheattribute-setun-ordered-step-label.
watermarkAllowedvaluesareoneormoreof'blank','ti-tle','toc','booklist','frontmatter','body','back-matter','in-dex','all'sep-aratedbywhite-space.
Specifieswhichpagesintheoutputdocumentaretobegivenawatermark.
Bydefault,allpagesaregivenawatermark.
Ifforexam-ple,parameterwatermarkissetto'frontmatterbodybackmatter',thenonlythepageswhicharepartofthefrontmatter,bodyandbackmatteroftheoutputdocumentaregiv-enawatermark.
Thetitlepage,TOCpages,etc,arenotgivenawatermark.
Noeffectunlessparameterwatermark-imageisspecified.
Chapter4.
XSLTstylesheetsparameters48XMLmindDITAConverterManualParameterValueDescriptionDefaultvalue:'all'.
xfc-render-as-tableAstringcontainingzeroormoreDI-TAelementnamesseparatedbywhite-space.
Defaultvalue:'note'.
SpecifieswhetherXMLmindXSL-FOConvertershouldren-derthesrepresentingspecifiedDITAelementsass.
ThisparameterenablesaworkaroundforalimitationofXMLmindXSL-FOConverter:ahavingabor-derand/orbackgroundcolorandcontainingseveralotherblocks,listsortablesisverypoorlyrenderedinRTF,WML,DOCXandODT.
Figure4-1.
PageareasHEADERFOOTERPAGEBODYpage-top-marginpage-bottom-marginpage-inner-marginpage-outer-marginbody-top-marginbody-bottom-marginheader-heightfooter-height1.
PageheadersandfootersSpecifyingaheaderorafooterTheheaderorthefooterofageneratedPDF,RTF,etc,pagehas3columns.
Chapter4.
XSLTstylesheetsparameters49XMLmindDITAConverterManualFigure4-2.
Layoutofaheaderheader-centerheader-leftheader-rightheader-center-widthheader-left-widthheader-right-widthheader-separatorThewidthofthesecolumnsmaybespecifiedusingtheheader-left-width,header-cen-ter-width,header-right-widthparametersfortheheaderandthefooter-left-width,foot-er-center-width,footer-right-widthparametersforthefooter.
Thewidthofacolumnisspecifiedasanintegerwhichislargerthanorequalto1.
Thisvalueisthepropor-tionalwidthofthecolumn.
Forexample,iftheleftcolumnhasawidthequalto2andtherightcolumnhasawidthequalto4,thissimplymeansthattherightcolumnistwice(4/2=2)aswideastheleftcolumn.
Thecontentsofthesecolumnsmaybespecifiedusingtheheader-left,header-center,head-er-rightparametersfortheheaderandthefooter-left,footer-center,footer-rightparametersforthefooter.
Whenheader-left,header-center,header-rightareallspecifiedastheemptystring,noheaderisgenerated.
Whenfooter-left,footer-center,footer-rightareallspecifiedastheemptystring,nofooterisgenerated.
Thecontentofacolumnisbasicallyamixoftextandvariables.
Example:"Page{{page-number}}of{{page-count}}".
Supportedvariablesare:{{document-title}}Thetitleofthedocument.
{{document-date}}Thepublicationdateofthedocument.
Thevalueofthevariablecomesfromthelastcreatedorrevisedelementfoundinthetop-icmeta/critdatesorbookmeta/critdateselementofthemap.
Moreprecisely,itcomesthevalueofattributegolive,modifiedordate,consideredinthatorder.
ThevalueofthisattributemustbesomethinglikeYYYY-MM-DD,becauseitisparsedandthenformattedaccordingtothexml:langofthemap.
Forexample,ifgolive="2014-02-23",withxml:lang="en",itgives:"February02,2014"andwithxml:lang="fr",itgives:"02Février2014".
Ifthemaphasnocritdateselement,thenthecurrentdateisused.
Ifthevalueofattributegolive,mod-ifiedordateisnotspecifiedasYYYY-MM-DD,thenthisvalueisusedasis.
{{chapter-title}}Thetitleofthecurrentpart,chapter,appendicesorappendix.
Emptyifthemapbeingconvertedisnotabookmap.
{{section1-title}}Thetitleofthecurrentpart,chapter,appendicesorappendixorsection1.
Asection1isspecifiedbyanon-typedtopicref(thatis,notapart,chapter,preface,appendix,dedi-cation,etc)whichisadirectchildofamaporbookmap.
Chapter4.
XSLTstylesheetsparameters50XMLmindDITAConverterManual{{topic-title}}Thetitleofthecurrenttopic.
Alltopicsareguaranteedtohaveacorresponding{{topic-ti-tle}}.
Evenautomaticallygeneratedtopicssuchastocorindexlisthaveacorresponding{{topic-title}}(7).
RestrictionIfyouuseXMLmindXSL-FOConvertertoconvertyourDITAdocumenttoRTF,WML,DOCXorODT,then{{section1-title}}and{{topic-ti-tle}}won'twork.
({{chapter-title}}worksfinethough.
)Thereasonofthislimitationisthat,unlikeotherXSL-FOprocessors,XMLmindXSL-FOConverterdoesnotimplementand.
{{page-number}}Currentpagenumberwithinthecurrentdocumentdivision(frontmatter,bodymatterorbackmatter).
{{page-count}}Totalnumberofpagesofthecurrentdocumentdivision(frontmatter,bodymatterorbackmatter).
{{break}}Alinebreak.
{{image(URI)}}AnimagehavingspecifiedURI.
ArelativeURIisresolvedagainstthecurrentworkingdirectory.
Example:"{{image(artwork/logo.
svg)}}".
{{page-sequence}}Notforproductionuse.
Insertsintheheader/footerthenameofthecurrentpagesequence.
Thisallowstolearnwhichnametouseinaconditionalheaderorfooter.
Seebelow.
ConditionalheadersandfootersThedefaultvalueofheader-centeris'{{document-title}}'.
Thismeansthateachpageofthegen-eratedPDF,RTF,etc,filewillhavethedocumenttitlecenteredonitstop.
ButwhatifyouwantthepagescontainingtheTableofContentshavea"Contents"headerIsthereawaytospecify:use"Contents"forthepagescontainingtheTableofContentsandusethetitleofthedocumentforanyotherpageThisisdonebyspecifyingthefollowingconditionalvalueforparameterheader-center:'toc::Con-tents;;{{document-title}}'.
Aconditionalvaluemaycontainoneormorecasesseparatedby";;".
Eachcaseistestedagainstthepagebeinggenerated.
Thefirstcasewhichmatchesthepagebeinggeneratedistheonewhichisselected.
conditional_value-->case[";;"case]*case-->[condition"::"]*valuecondition-->[test_page_sequence]&[Stest_page_layout]&[Stest_page_side](7)The{{topic-title}}ofatocis"TableofContents",properlylocalized.
The{{topic-title}}ofain-dexlistis"Index",properlylocalized.
Chapter4.
XSLTstylesheetsparameters51XMLmindDITAConverterManualLet'ssupposeyoualsowantthethepagescontainingtheIndexhavea"Index"header.
Specifying'toc::Contents;;{{document-title}};;indexList::Index'won'tworkasexpectedbecausethesecondcase(havingnoconditionatall)matchesanypage,includingtheIndexpages.
Youneedtospecify:'toc::Contents;;indexlist::Index;;{{document-title}}'.
Let'srememberthatvariable{{topic-title}}issubstitutedwiththetitleofthecurrenttopic,includingautomaticallygeneratedtopicssuchtocandindexlist.
Thereforeourconditionalvalueisbetterexpressedas:'toc::indexlist::{{topic-title}};;{{document-title}}'.
Noticehowacasemayhaveseveralconditions.
Sufficeforanyofthesecondi-tionstomatchthepagebeinggeneratedforthecasetobeselected.
Evenbetter,specify'toc||indexlist::{{topic-title}};;{{document-title}}'.
String"||"maybeusedtoseparatealternativevaluestobetestedagainstthepagebeinggenerated.
test_page_sequence-->page_sequence["||"page_sequence]*page_sequence-->"abbrevlist"|"amendments"|"appendices"|"appendix"|"backmattersection"|"bibliolist"|"bookabstract"|"booklist"|"chapter"|"colophon"|"dedication"|"draftintro"|"figurelist"|"glossarylist"|"indexlist"|"notices"|"part"|"preface"|"section1"|"tablelist"|"toc"|"trademarklist"TipIt'snotdifficulttoguessthatthenameofthepagesequencecorrespondingtotheTableofContentsistocandthatthenameofthepagesequencecorrespondingtotheIndexisindexlist.
Howeverthesimplestwaytolearnwhatisthenameofthepagesequencebeinggeneratedistoreferencevariable{{page-sequence}}inthespecificationofaheaderorafooter.
Nowlet'ssupposethatwewanttosuppressthedocumenttitleonthefirstpageofapart,chapterorappendix.
Thisisspecifiedasfollows:'firstpart||chapter||appendix::;;toc||indexlist::{{top-ic-title}};;{{document-title}}'.
Fornow,wehaveonlydescribedaconditionaboutthepagesequencebeinggenerated:TOC,Index,etc.
Infact,aconditionmaytestupto3facetsofthepagebeinggenerated:Thepagesequencetowhichbelongsthepagebeinggenerated.
Whetherthepagebeinggeneratedispartofaone-sidedoratwo-sideddocument.
Whetherthepagebeinggeneratedisthefirstpageofitssequence.
Whenthethepagebeinggeneratedisnotthefirstpageofitssequence,ifthepagebeinggeneratedhasanoddoranevenpagenumber.
test_page_layout-->page_layout["||"page_layout]*page_layout-->"two-sides"|"one-side"test_page_side-->page_side["||"page_side]*page_side-->"first"|"odd"|"even"Chapter4.
XSLTstylesheetsparameters52XMLmindDITAConverterManualRememberWhenthedocumenthasoneside,theonlypossiblepagesideisodd.
Theothervalues,firstandeven,arenotsupported.
Forexample,somethinglike'one-sidechap-ter||appendixeven::{{chapter-title}};;'cannotgenerateanytext.
Theorderofthetestsisnotsignificant.
Forexample,'firstpart||chapter||appendix'isequivalentto'part||chapter||appendixfirst'.
Therefore'firstpart||chapter||appendix::;;toc||indexlist::{{topic-title}};;{{document-title}}'readsasfollows:1.
Usetheemptystringforthefirstpageofapart,chapterorappendix.
2.
UsethetopictitleforthepagescontainingtheTableofContents.
Thistitleis"TableofContents",butlocalizedaccordingtothemainlanguageoftheDITAdocumentbeingconverted.
3.
UsethetopictitleforthepagescontainingtheIndex.
Thistitleis"Index",butlocalizedaccordingtothemainlanguageoftheDITAdocumentbeingconverted.
4.
Foranyotherpage,usethetitleoftheDITAdocument.
NoteEverythingexplainedinthissectionappliesnotonlytothecontentsofacolumnofaheaderorfooter,butalsototheproportionalwidthofacolumnofaheaderorfooter.
Example:-pfooter-right-width"first||odd::4;;even::1".
Chapter4.
XSLTstylesheetsparameters53XMLmindDITAConverterManualChapter5.
ControllingthenumberingoforderedlistsThischapterexplainshowyoucantocontrolthenumberingoforderedlistsbythemeansofoneormoredirectivesspecifiedinthe@outputclassattributeoftheelement.
Bydefault,thenumberingofnestedorderedlistsautomaticallyalternatesbetweenthe"1.
"and"a.
"formats.
Ifyouwantmorecontrolonthenumberingoforderedlists,thenyou'llhavetospecifyoneormoreofthefollowingdirectivesinthe@outputclassattributeoftheelement.
lower-alphaupper-alphalower-romanupper-romandecimalSpecifiesthestyleofnumbering.
start(positive_integer)Numberingbeginsatspecifiedpositive_integer.
continueNumberingbeginswheretheprecedingorderedlistleftoff.
inheritnumNumberinginheritsfromouter-levelorderedlists.
Forexample,usingthisfeature(e.
g.
),theitemsofalistnestedatlevel2arelabelled"1.
A.
","1.
B.
","1.
C.
",etc.
RestrictionWhenusingXMLmindXSL-FOConverterv6.
0+(8)togenerateRTF,WML,DOCXorODT,directiveinheritnumissupportedbutwithminorlimitations.
Forexample,whenbothstart(positive_integer)andinheritnumarespecified,inheritnumisnothonored.
DirectiveinheritnumisnothonoredwhengeneratingJavaHelpandHTMLHelp.
Example:specifiesanorderedlistwhichstartswithan"X.
".
Notethatitisstillpossibletospecifyanyclassnameyouwantinthe@outputclassattributeoftheelement.
Example:.
(8)v6.
1+stronglyrecommended.
Chapter5.
Controllingthenumberingoforderedlists54XMLmindDITAConverterManualChapter6.
GivingabackgroundcolortotablecellsThischapterexplainshowyoucangiveabackgroundcolortotablecellsbyaddingabgcolor(color)directivetothe@outputclassattributeofmosttableelements.
It'spossibletogiveabackgroundcolortotablecellsbyaddingabgcolor(color)directive,wherecolorisanyCSScolorvalue,tothe@outputclassattributeofthefollowingelements:Insideaelement,,,.
Insideaelement,,,,.
Example:C1,1C1,2C2,1C2,2Notethatitisstillpossibletospecifyanyclassnameyouwantinthe@outputclassattributeofatableelement.
Example:.
Chapter6.
Givingabackgroundcolortotablecells55XMLmindDITAConverterManualChapter7.
FancycodeblocksThissectionexplainshowyoucanautomaticallyaddlinenumbers,"expand"tabcharactersandcolorizethesourcecodecontainedin,oranyotherelementspecializing.
Addinglinenumbers,"expanding"tabcharactersandcolorizingthesourcecodecontainedin,oranyotherelementspecializingisdonebyaddingoneormoreofthefollowingclassestothe@outputclassattributeofthiselement:line-numbersline-numbers-N(whereNisaninteger>0)show-line-numbersGiveanumbertothelinescontainedintheelement.
Bydefault,firstlinenumberis1.
Thisfirstlinemaybespecifiedusingthesecondformoftheline-numbersclass,forexample,line-numbers-100specifiesthatlinesaretobenumberedandthatfirstlinenumberis100.
show-line-numbers,analiasforline-numbers-1,isalsoacceptedforcompatibilitywiththeDITA-OT.
language-L(whereLislanguagename)Colorizethesourcecodecontainedintheelement.
L,a"programminglanguage"suchasc,java,css,xml,specifieshowthesourcecodeshouldbecolorized.
Moreinformationaboutthisfeature,commonlycalledsyntaxhighlighting,innextsection.
tab-width-W(whereWisaninteger>=0)normalize-spaceSpecifieswhethertabcharactersshouldbeexpandedtoanumberofspacecharacters.
Wisthemaximumnumberofspacecharactersforanexpandedtabcharacter,hencethisvaluespecifiesthelocationof"tabstops".
Examples:tab-width-4means:expandtabstoupto4spacecharacters;tab-width-0means:donotreplacetabsbyspacecharacters.
Inadditiontoreplacingtabcharactersbyanumberofspacecharacters,tab-width-W(whereW>0)alsoremovesthespacecharacterswhicharecommontothebeginningofalltextlines.
Thatis,itremovesthesuperfluous"indentation"intheelement,ifany.
Seeexamplebelow.
Moreovertab-width-W(whereW>0)alsoremovesthe(useless)spacecharactersfoundjustbeforenewlinecharacters.
normalize-space,analiasfortab-width-8,isalsoacceptedforcompatibilitywiththeDI-TA-OT.
RememberWhentheattributeofanyelementspecializingcontainsclassline-numbers/line-numbers-Nand/orclasslanguage-L,thenclasstab-width-8isimplicitlyspecifiedtoo,thatis,whitespacenormalizationisautomaticallyperformed.
Ifthisisnotwhatyouwant,pleaseexplicitlyaddclasstab-width-0to@outputclass.
Example:asimpleCprogramfeaturinglinenumberingandsyntaxhighlightingInthefollowingCprogram,linesareindentedusingtabcharacters.
Chapter7.
Fancycodeblocks56XMLmindDITAConverterManual12345678/*HelloWorld*/#include<stdio.
h&ght;intmain(){printf("HelloWorld\n");return0;}isrenderedas:12345678/*HelloWorld*/#includeintmain(){printf("HelloWorld\n");return0;}Example:superfluousindentationisremovedbytab-width-N(whereN>0)Attribute@outputclassimplicitlyalsocontainstab-width-8.
Firstline"/tmp/"startswith4spacecharacters.
1234567891011/tmp//usr/bin/lib/local/bin/lib/src/src//var/isrenderedas:1234567891011/tmp//usr/bin/lib/local/bin/lib/src/src//var/Chapter7.
Fancycodeblocks57XMLmindDITAConverterManual1.
SyntaxhighlightingThissectionexplainshowyoucanautomaticallycolorizethesourcecodecontainedin,oranyotherelementspecializing.
Youcanautomaticallycolorizethesourcecodecontainedin,oranyotherelementspecializing.
Thisfeature,commonlycalledsyntaxhighlighting,hasbeenimplementedusinganopensourcesoftwarecomponentcalled"XSLTsyntaxhighlighting".
IfyouwanttoturnonsyntaxhighlightinginaDITAdocument,sufficetoaddattribute@outputclasstoa,oranyotherelementspecializing.
Thevalueofattribute@output-classmustbeanyof:language-bourne(or-shellor-sh),language-c,language-cmake(or-makeor-makefile),language-cpp,language-csharp,language-css21(or-css),language-delphi,language-ini,language-java,language-javascript,language-lua,language-m2(Modula2),language-perl,language-php,language-python,language-ruby,language-sql1999,lan-guage-sql2003,language-sql92(or-sql),language-tcl,language-upc(UnifiedParallelC),language-html,language-xml.
IfyouwanttocustomizesyntaxhighlightingforanHTML-basedoutputformat(XHTML,EPUB,etc),thenredefineanyofthefollowingCSSstyles:.
hl-keyword(keywordsofaprogramminglanguage),.
hl-string(stringliteral),.
hl-number(numberliteral),.
hl-comment(anytypeofcomment),.
hl-doccomment(commentsusedasdocumentation,i.
e.
javadoc,orxmldoc),.
hl-directive(preprocessordirectiveorinXML,aprocessing-instruction),.
hl-annotation(annotationsor"attributes"astheyarecalledin.
NET),.
hl-tag(XMLtag,i.
e.
elementname),.
hl-attribute(XMLattributename),.
hl-value(XMLattributevalue),.
hl-doctype(andallitscontent).
Example:customizationofthesyntaxhighlightingofakeywordforHTML-basedoutputformats.
hl-keyword{font-weight:bold;color:#602060;}HowtouseacustomCSSstylesheetisexplainedinPartII,Chapter9,Section1.
IfyouwanttocustomizesyntaxhighlightingforanXSL-FO-basedoutputformat(PDF,RTF,etc),thenredefineanyofthefollowings:hl-keyword,hl-string,hl-number,hl-comment,hl-doccomment,hl-directive,hl-annotation,hl-tag,hl-attribute,hl-value,hl-doctype.
Example:customizationofthesyntaxhighlightingofakeywordforXSL-FO-basedoutputformatsbold#602060Chapter7.
Fancycodeblocks58XMLmindDITAConverterManualHowtouseacustomXSLTstylesheetgeneratingXSL-FOisexplainedinPartII,Chapter9,Section2.
Chapter7.
Fancycodeblocks59XMLmindDITAConverterManualChapter8.
RichmediacontentThischapterexplainshowtoaddSVG,MathML,audio,videoandFlashanimationstoyourDITAtopicsandhowditacprocessesthisrichmediacontentinthecasewheretheoutputformatsupportsrichmedia(e.
g.
XHTML5,EPUB3)andalsointhecasewheretheoutputformatdoesnotsupportrichmedia(e.
g.
XHTML1,PDF,RTF).
SVGItispossibletoincludeSVGgraphicsinaDITAdocumenteitherbyreferenceorbyinclusion.
Usean/elementpointingtoanSVGfiletoincludeitbyreference.
Example:TheXMLsourcecodecorrespondingtotheaboveexampleis:It'salsopossibletouseanelementpointingtoanSVGfiletoincludeitbyreference.
Example:EmbeddingSVGgraphicsinaDITAdocumentcanbeachievedusingthesameele-ment.
Example:TheXMLsourcecodecorrespondingtotheaboveexampleis:.
.
.
Notes:ItisstillrecommendedtoincludeSVGgraphicsbyreferenceusingtheelementratherthen/.
Theelementhasusefulattributes(@width,@height,@scale,@scalefit)allowingtoadjustthedimensionoftheimage.
Moreoverthiselementspermitsontheflyconversionbetweenimageformats.
ItisnotrecommendedtoembedSVGgraphicsinaDITAdocumentasthisislikelytocausemanyvalidationproblems.
OnlythefollowingscreenformatsmaycontainSVG:XHTML5,XHTML5WebHelpandEPUB3.
NotethatonlymodernwebbrowserssupportXHTML5andXHTML5WebHelp.
VeryfewEPUBreaders(e.
g.
iBooks)supportEPUB3.
AllXSL-FObasedformats(PDF,RTF,DOCX,etc)supportSVGwhatevertheXSL-FOprocessoryoumayuse.
Chapter8.
Richmediacontent60XMLmindDITAConverterManualMathMLItispossibletoincludemathinaDITAdocumenteitherbyreferenceorbyinclusion.
Usean/elementpointingtoaMathMLfiletoincludeitbyreference.
Example:TheXMLsourcecodecorrespondingtotheaboveexampleis:EmbeddingMathMLinaDITAdocumentcanbeachievedusingthesameelement.
Example:TheXMLsourcecodecorrespondingtotheaboveexampleis:.
.
.
Notes:Forclarity,itisrecommendedtowrapintothefollowingequationelements:,,.
Thereisanoptiontonumberelementshavinga.
Example:Equation8-1.
Gauss'slawinitsdifferentialformelementscontainingaemptyareautomaticallynum-bered.
Example:(8-1)Thecounterusedtonumbertoelementshavingaandthecounterusedtonumberelementscontaininganemptyaredifferent.
ThereforemixingnumberedsandnumberedsinthesameDITAdocumentmayresultinahardtounderstandequationnumbering.
OnlythefollowingscreenformatsmaycontainMathML:XHTML5,XHTML5WebHelpandEPUB3.
Mostmodernwebbrowsers(Firefox,Chrome)supportXHTML5andXHTML5WebHelpcontainingMathML.
VeryfewEPUBreaders(e.
g.
iBooks)supportEPUB3.
XSL-FObasedformats(PDF,RTF,DOCX,etc)supportMathMLdependingontheXSL-FOprocessoryouuse:–ApacheFOPrequiresyoutodownloadandinstallthetheJEuclidFOPplug-in.
–RenderXXEPdoesnotsupportMathML.
Chapter8.
Richmediacontent61XMLmindDITAConverterManual–AntennaHouseFormattersupportsMathMLasanoption.
–XMLmindXSL-FOConvertersupportsMathMLoutofthebox.
AudioUsetheDITAelementtoaddaudiotoyourDITAtopics.
Example:audio.
mp3(audio/mpeg)TheXMLsourcecodecorrespondingtotheaboveexampleis:Notes:The@dataand@typeattributesarerequired.
Thevalueofthe@typeattributemuststartwith"au-dio/".
Itisstronglyrecommendedtospecifyalternateaudiofilesasmodernwebbrowsers,whileallsup-portingtheHTML5element,varyintheirsupportofaudioformats.
Thisisdonebyaddingchildelementstotheelement.
Suchelementsmusthaveaname="source"attribute,avaluetype="ref"attribute,a@valueattributereferencinganaudiofileandpreferably,a@typeattributespecifyingthemediatypeoftheaudiofile.
ItispossibletoaddelementscorrespondingtotheattributessupportedbytheHTML5audioelement(,,,,,,).
Intheaboveexample,wehaveaddedaelementcorrespondingtothe@controlsHTML5attribute.
NotethatinthecaseofHTML5booleanattributes(,,,),the@valueattributeofaisnotsignificant.
Forexample,inthecaseoftheaboveexample,youcouldhavespecified"yes","on","1",etc,insteadof"true".
Iftheelementhasachildelement,thenthiselementisusedtogeneratefallbackcontentincaseaudioisnotsupported.
Iftheobjectelementhasnochildelement,thenasimplefallbackcontentisautomaticallygeneratedbyditac.
Thisautomaticfallbackcontentbasicallyconsistsinalinkallowingtodownloadtheaudiofile.
WhenditacisusedtogenerateanXSL-FObasedformat(PDF,RTF,etc),onlythefallbackcontentappearsintheoutputfile.
LightweightDITAhasanelement,sothereisnoneedtouseanelement.
Theequivalentoftheaboveexamplewouldbe:Chapter8.
Richmediacontent62XMLmindDITAConverterManualVideoUsetheDITAelementtoaddvideotoyourDITAtopics.
Example:video.
mp4(video/mp4)TheXMLsourcecodecorrespondingtotheaboveexampleis:Notes:The@dataand@typeattributesarerequired.
Thevalueofthe@typeattributemuststartwith"video/".
Itisstronglyrecommendedtospecifyalternatevideofilesasmodernwebbrowsers,whileallsup-portingtheHTML5element,varyintheirsupportofvideoformats.
Thisisdonebyaddingchildelementstotheelement.
Suchelementsmusthaveaname="source"attribute,avaluetype="ref"attribute,a@valueattributereferencingavideofileandpreferably,a@typeattributespecifyingthemediatypeofthevideofile.
ItispossibletoaddelementscorrespondingtotheattributessupportedbytheHTML5element(,,,,,,,,,).
Intheaboveexample,wehaveaddedaelementcorrespondingtothe,andHTML5attributes.
NotethatinthecaseofHTML5booleanattributes(,,,),the@valueattributeofaisnotsignificant.
Forexample,inthecaseoftheaboveexample,youcouldhavespecified"true","on","1",etc,insteadof"yes".
Iftheelementhasachildelement,thenthiselementisusedtogeneratefallbackcontentincasevideoisnotsupported.
Iftheobjectelementhasnochildelement,thenasimplefallbackcontentisautomaticallygeneratedbyditac.
Thisautomaticfallbackcontentbasicallyconsistsinalinkallowingtodownloadthevideofile.
TheelementcorrespondingtotheHTML5attribute,ifpresent,isusedtogenerateanicerautomaticfallbackcontent.
WhenditacisusedtogenerateanXSL-FObasedformat(PDF,RTF,etc),onlythefallbackcontentappearsintheoutputfile.
Chapter8.
Richmediacontent63XMLmindDITAConverterManualLightweightDITAhasanelement,sothereisnoneedtouseanelement.
Theequivalentoftheaboveexamplewouldbe:FlashanimationUsetheDITAelementtoaddAdobeFlashanimationstoyourDITAtopics.
Example:animation.
swf(application/x-shockwave-flash)(Youmayhavetoright-clickontheabovescreenshotandselectPlayfromtheFlashpopupmenutoreplaytheanimation.
)TheXMLsourcecodecorrespondingtotheaboveexampleis:Notes:The@data,@type,@widthand@heightattributesarerequired.
Theparamname=moviechildelementhavingthesamevalueasattribute@dataisrequiredtoo.
YoumayaddanyotherchildelementsupportedbytheFlashobject.
Intheaboveexample,you'llfindmenuandqualityinadditiontorequiredmovie.
Iftheelementhasachildelement,thenthiselementisusedtogeneratefallbackcontentincaseFlashisnotsupported.
Iftheobjectelementhasnochildelement,thenasimplefallbackcontentisautomaticallygeneratedbyditac.
Thisautomaticfallbackcontentbasicallyconsistsinalinkallowingtodownloadthe.
swffile.
WhenditacisusedtogenerateanXSL-FObasedformat(PDF,RTF,etc),onlythefallbackcontentappearsintheoutputfile.
OtherusesoftheelementWehaveseeninprevioussectionshowtheDITAelementmaybeusedtoaddaudio,videoandAdobeFlashanimationstoyourDITAtopics.
Inanycaseotherthanthosedescribedinprevioussections,theDITAelementisconvertedtotheequivalentXHTMLelement.
Forexample,ifChapter8.
Richmediacontent64XMLmindDITAConverterManualyouwanttoaddaYouTubevideotoyourDITAtopics,simplydoitinDITAasyouwoulddoitinXHTMLusingtheelement.
WatchthistestvideoonYouTube.
TheXMLsourcecodecorrespondingtotheaboveexampleis:WatchthistestvideoonYouTube.
Notes:Iftheelementhasachildelement,thenthiselementisusedtogeneratefallbackcontentincasethemediaobjectisnotsupported.
Iftheobjectelementhasnochildelement,thenasimplefallbackcontentisautomaticallygeneratedbyditac.
Thisautomaticfallbackcontentbasicallyconsistsinalinkallowingtodownloadthemediafile.
WhenditacisusedtogenerateanXSL-FObasedformat(PDF,RTF,etc),onlythefallbackcontentappearsintheoutputfile.
ActionsUnlessyouaddparamname="controls"(seeabove),you'llnotbeabletoplayaudioorvideo.
Evenworse,withoutthecontrols,anaudioobjectisnotrenderedonscreen(thatis,itisinvisible).
Asimplesolutionforthisproblemistoinsertaprocessing-instructioninaDITAelement(typicallyaninlineelementsuchasor).
Theprocessing-instructionallowstospecifyannumberofactions:playPlaytheassociatedresourcefromthebeginning.
Onlyapplicabletovideooraudiotargets.
pausePauseplaying.
Onlyapplicabletovideooraudiotargets.
resumeResumeplaying.
Onlyapplicabletovideooraudiotargets.
muteMutesound.
Onlyapplicabletovideooraudiotargets.
unmuteUnmutesound.
Onlyapplicabletovideooraudiotargets.
showSetthevisibilitypropertyofthetargetelementtovisible.
hideSetthevisibilitypropertyofthetargetelementtohidden.
TheaboveactionsareexactlythosesupportedbyEPUB3's.
Theprocessing-instructionisprocessedbyditacforthefollowingoutputformats:XHTML5,XHTML5WebHelpandEPUB3.
Itisdiscardedforanyotheroutputformat.
Thesyntaxforthecontentofis:onclick_data->action(Saction)*action->op'('target_id')'Chapter8.
Richmediacontent65XMLmindDITAConverterManualop->'play'|'pause'|'resume'|'mute'|'unmute''show'|'hide'Whentarget_idisnotspecified,itistakenfromthe@hrefattributeoftheelementcontainingtheprocessing-instruction.
Forexample,isequivalentto:.
Example1:Say:"ViensHubble!
",which,inFrench,means:"ComehereHubble!
".
Noaudio.
Say:"ViensHubble!
",which,inFrench,means:"ComehereHubble!
".
TheXMLsourcecodecorrespondingtotheaboveexampleis:Example1:Say"ViensHubble!
".
.
.
.
.
.
Example2:HideHubble.
ShowHubble.
Figure8-1.
MynameisHubble.
I'ma7-montholdGoldenRetriever.
TheXMLsourcecodecorrespondingtotheaboveexampleis:Example2:HideHubble.
ShowHubble.
Chapter8.
Richmediacontent66XMLmindDITAConverterManualPartII.
CustomizingtheoutputofXMLmindDITAConverterPartII.
CustomizingtheoutputofXMLmindDITAConverter67XMLmindDITAConverterManualChapter9.
Simplecustomization1.
Customizethelookofthe(X)HTMLpagesgeneratedbyditacWe'llexplainhowtocustomizethelookofthe(X)HTMLpagesgeneratedbyditacbyusinganexample.
Let'ssupposewewanttorendertopictitlesinanicedarkbluecolorratherthaninblack.
AboutthistaskTheeasiestwaytocustomizethelookofthe(X)HTMLpagesgeneratedbyditacistouseacustomCSSstylesheetratherthanthestockone.
Procedure1.
CreateacustomCSSstylesheetimportingthestockCSSstylesheet.
ThestockCSSstylesheetisfoundin:ditac_install_dir/xsl/xhtml/resources/base.
cssUsedfortheXHTML1.
0,XHTML1.
1,HTML4.
01andXHTML5outputformats.
ditac_install_dir/xsl/webhelp/resources/base.
cssUsedfortheWebHelpoutputformat.
ditac_install_dir/xsl/htmlhelp/resources/base.
cssUsedfortheHTMLHelpoutputformat.
ditac_install_dir/xsl/eclipsehelp/resources/base.
cssUsedfortheEclipseHelpoutputformat.
ditac_install_dir/xsl/javahelp/resources/base.
cssUsedfortheJavaHelpoutputformat.
ditac_install_dir/xsl/epub/resources/base.
cssUsedfortheEPUBoutputformat.
InitialcontentsofthecustomCSSstylesheet(acopyofthisfileisfoundincustomize/custom.
css).
@importurl(base.
css);RestrictionMicrosoftHTMLHelpviewerhh.
exedoesnotsupport@import.
Thereforeyoumustcopybase.
cssintoyourcustomCSSstylesheetifyougenerateHTMLHelp.
2.
AddoneormorerulestothecustomCSSstylesheet.
TheXSLTstylesheetsgenerating(X)HTMLpagesmakeextensiveuseoftheclassattribute.
GenerallytheXHTMLelementgeneratedforaDITAelementhasaclassattributebearingthenameoftheDITAelement.
Example:aDITAisconvertedtoaXHTML.
Formoreinformation,you'llhavetorefertothestockCSSstylesheetoreventothe(X)HTMLpagesgeneratedbyditac.
@importurl(base.
css);Chapter9.
Simplecustomization68XMLmindDITAConverterManual.
part-title,.
chapter-title,.
appendix-title,.
section1-title,.
section2-title,.
section3-title,.
section4-title,.
section5-title,.
section6-title,.
section7-title,.
section8-title,.
section9-title,.
topic-title{color:#403480;border-bottom:2pxsolid#403480;}3.
Specifythe"-pcustom-csscustomize/custom.
css"optionwhenrunningditac.
$ditac-imagesimg-pxsl-resources-directoryres\-pcustom-csscustomize/custom.
css\out/manual/_.
htmlmanual.
ditamapTheabovecommandgivestheexpectedresultsbecause:1.
"-pxsl-resources-directoryres"copiesallstockresources,includingbase.
css,tosubdirectoryout/manual/res/.
2.
"-pcustom-csscustomize/custom.
css"copiescustom.
csstosubdirectoryout/man-ual/res/.
2.
CustomizingthelookofthePDFfilesgeneratedbyditacWe'llexplainhowtocustomizethelookofthePDFfilesgeneratedbyditacbyusinganexample.
Let'ssupposewewanttorendertopictitlesinanicedarkbluecolorratherthaninblack.
AboutthistaskAPDFfileiscreatedbyconvertingtheXSL-FOfilegeneratedbytheditacXSLT2.
0stylesheetbythemeansofanXSL-FOprocessorsuchasApacheFOP,RenderXXEPorAntennaHouseFormatter.
ThereforeweneedtogenerateacustomXSL-FOfile.
ThisisdonebycreatingaverysimplevariantofthestockXSLTstylesheetwhichgeneratesXSL-FO.
Procedure1.
CreateacustomXSLTstylesheetimportingthestockone.
ThisstockXSLTstylesheetisfoundinditac_install_dir/xsl/fo/fo.
xsl.
ItisusedtogenerateanintermediateXSL-FOfile.
Afterthat,theXSL-FOfileisconvertedtoPDF,PostScript,RTF,WordprocessingML,OfficeOpenXML(.
docx)orOpenOffice/LibreOffice(.
odt)bythemeansofanXSL-FOprocessor.
InitialcontentsofthecustomXSLTstylesheet(acopyofthisfileisfoundincustomize/custom_fo.
xsl).
NoticethefunnylookingURI"ditac-xsl:fo/fo.
xsl".
"ditac-xsl:"isaneasywaytorefertoditac_install_dir/xsl/.
ThisworksbecausetheXMLcatalogusedbytheditaccommand-lineutility(foundinditac_install_dir/schema/catalog.
xml)contains:2.
Redefineoneormorenamedxsl:attribute-setsinyourcustomXSLTstylesheet.
Namedxsl:attribute-setsarenotdocumentedyet.
Formoreinformation,you'llhavetorefertotheXSLTstylesheetsfoundinditac_install_dir/xsl/fo/.
#403480160%0.
05em0.
5ptsolid#4034801.
5em1.
2em1.
8em3.
Specifythe"-tcustomize/custom_fo.
xsl"optionwhenrunningditac.
$ditac-tcustomize/custom_fo.
xsl\out/manual.
pdfmanual.
ditamapAlternatively,packageyourcustomXSLTstylesheetasaplug-inandthenspecifythenameofthisplug-inusingthe-plugincommand-lineoption.
Bydoingthis,yourcustomXSLTstylesheetwillbeautomaticallyusedwhatevertheoutputformatwhichusesXSL-FOasitsintermediateformat(PDF,RTF,.
odt,.
docx,etc).
Chapter9.
Simplecustomization70XMLmindDITAConverterManualChapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecializationWe'llexplainbyexamplehowtouseditactoconvertdocumentsconformingtoaDITAspecialization.
Let'ssupposewehaveaDITAspecializationwhichaddsandelements(similartoandHTML5elements)topiccontents.
Theseelementsaremodeledasfollows(seesample_plugin/dtd/sampleDomain.
mod)Alltheexamplefilesofthistutorialhavebeenpackagedasaplug-incalled"sample_plugin".
Theyarefoundindirectorysample_plugin/.
Inordertogivethisplug-inatry,you'llhavetocopydirectorysam-ple_plugin/toditac_install_dir/plugin/.
AboutthistaskUsingditactoconvertdocumentsconformingtoaDITAspecializationbasicallyrequirescustomizingtheoutputofthetoolusingthesametechniquesasthoseexplainedinChapter9,Section1andChapter9,Section2.
Procedure1.
CreateanXMLcatalogpointingtoalocalcopyofyourcustomDTD.
Thisfilemustbenamedcata-log.
xmlandmustbefoundinyourplug-indirectory.
Filesample_plugin/catalog.
xml:Chapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecialization71XMLmindDITAConverterManual.
.
.
2.
Createacustomizationofditac_install_dir/xsl/xhtml/xhtml.
xslasexplainedinChapter9,Section2.
Thisfilemustbefoundinyour_plugin_dir/xsl/xhtml/xhtml.
xslinordertobeusedbyditac.
Filesample_plugin/xsl/xhtml/xhtml.
xsl:NotethattheXSLTtemplatecalledcommonAttributesaddsaclass="kbd"attributetothegener-atedelement.
Similarly,itaddsaclass="time"attributetotheelementgeneratedfortheelement.
Sohowtostylethegeneratedanda.
Copyditac_install_dir/xsl/xhtml/resources/andditac_install_dir/xsl/xhtml/resources.
listtoyour_plugin_dir/xsl/xhtml/.
b.
Copythefollowingxhtml.
cssCSSstylesheettoyour_plugin_dir/xsl/xhtml/resources/.
@importurl(base.
css);.
kbd{font-family:monospace;font-size:90%;Chapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecialization72XMLmindDITAConverterManualborder:1pxsolid#C0C0C0;border-radius:3px;-moz-border-radius:3px;-webkit-border-radius:3px;padding:2px;background-color:#F0F0F0;}.
time{background-color:#FFFFCC;padding:2px;}c.
Appendthefollowinglinetoyour_plugin_dir/xsl/xhtml/resources.
list.
resources/xhtml.
cssd.
DeclarethatthedefaultCSSstylesheetisxhtml.
cssandnotstockbase.
css.
ThisisdonebyusingXSLTstylesheetparametercssResourceName.
.
.
.
3.
Createacustomizationofditac_install_dir/xsl/fo/fo.
xslasexplainedinChapter9,Section2.
Thisfilemustbefoundinyour_plugin_dir/xsl/fo/fo.
xslinordertobeusedbyditac.
Filesample_plugin/xsl/fo/fo.
xsl:1pxsolid#C0C0C0#F0F0F00.
25em.
.
.
Chapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecialization73XMLmindDITAConverterManual4.
Passcommand-lineoption-pluginplugin_nametoditacinordertousetheDTDs(orschemas)andtheXSLTstylesheetsfoundinyourplug-insubdirectory,preferablytothosefoundinditac_in-stall_dir/schema/andinditac_install_dir/xsl/.
You'llfindasampleDITAdocumentmakinguseofthecustomandelementsinsam-ple_plugin/sample/sample.
ditamap.
Youcanconvertthissampledocumenttosingle-pageXHTMLandtoPDFbyrunningsample_plugin/sample/run.
sh(sample_plugin\sample\run.
batonWindows):bin/ditac-pluginsample_plugin\out/sample.
pdfsample.
ditamapChapter10.
UsingditactoconvertdocumentsconformingtoaDITAspecialization74XMLmindDITAConverterManualChapter11.
ExtensivecustomizationInordertoextensivelycustomizetheoutputofditac,youneedtolearnhowitworks.
Basically,thismeansthatyou'llhavetounderstandthecontentsoftheditac_lists.
ditac_listfileandthe.
ditacfiles,whicharegeneratedbytheditacpreprocessor.
Anextensivecustomizationworksexactlylikeasimpleone:1.
CreateacustomXSLT2.
0stylesheetwhichimportsthestockone.
2.
Redefineoneormoreattributesetsand/oroneormoretemplatesinthecustomXSLT2.
0stylesheet.
Theonlydifferenceisthatthistime,youneedtoknowexactlywhatistheformatofthefilesyouaregoingtotransform.
Thebadnewsfirst:theditacXSLT2.
0stylesheetsdonottransformplainDITAfiles.
Theytransform.
ditacfiles,whicharefullypreprocessedDITAfiles.
Now,thegoodnews:.
ditacfilesmainlycontainsDITAelementsandbecausetheditacpreprocessorperformsallthegruntworkbeforehand,.
ditacfilesarereallystraightforwardtotransform.
Infact,transforming.
ditacfilesratherthanplainDITAfilesallowstoconcentrateoncreatinggreat-lookingoutput.
HowitworksTheditacpreprocessorgeneratesasingleditac_lists.
ditac_listfileandoneormore.
ditacfiles(9)outofthesourceDITAfiles.
Figure11-1.
TheintermediatefilesgeneratedbytheditacpreprocessorXMLmindDITAPreProcessorXMLmindDITAXSLT2.
0StylesheetsSaxonXSLT2.
0Engine.
ditacfilesditac_lists.
ditac_listsDITAfilesXSL-FOfileXHTMLfilesThen,each.
ditacfile,whichmainlycontainsfullypreprocessedDITAtopics,istransformedinturnbytheditacXSLT2.
0stylesheets.
Theditac_lists.
ditac_listfile,whichcontainsusefulinformationabouttheoverallDITAdocumentbeingconverted,isnotdirectlytransformedbytheditacXSLT2.
0stylesheets.
Instead,whenneededto,theditacXSLT2.
0stylesheetsquerytheditac_lists.
ditac_listfileinordertogenerateoptionalitems.
Example:numbertopics,tables,figures,etc,whenparameternumber='XXX'hasbeenspecified.
Itispossibletoexaminethecontentsoftheditac_lists.
ditac_listfileandthoseofthe.
ditacfilesbyspecifyingthe-preprocesscommand-lineoption.
Example:$ditac-preprocess\-v-chunksingle\-imagesimg-pxsl-resources-directoryres\out/manual.
htmlmanual.
ditamap(9)Asingle.
ditacfileforaprintoutput;oneormore.
ditacfilesforascreenoutput.
Chapter11.
Extensivecustomization75XMLmindDITAConverterManualContentsofa.
ditacfileTherootelementofa.
ditacfileis.
Aelementmayhavethefollowingchildelements(inanyorderandinanynumber):Thisemptyplaceholderelementmeans:generatea``titlepage''sectionhere.
Thisemptyplaceholderelementmeans:generateaTableofContentssectionhere.
Thisemptyplaceholderelementmeans:generateaListofFiguressectionhere.
Thisemptyplaceholderelementmeans:generateaListofTablessectionhere.
Thisemptyplaceholderelementmeans:generateaListofExamplessectionhere.
Thisemptyplaceholderelementmeans:generateaListofEquationssectionhere.
Thisemptyplaceholderelementmeans:generateanIndexsectionhere.
ADITAtopicofanykindAfullypreprocessedtopic.
Thistopicisguaranteednottocontainnestedtopics.
Wrapperelementsusedtoimplementflagginginditac.
Flaggingisspecifiedbythemeansofaconditionalprocessingprofile(a.
ditavalfile).
Seealsothe-filtercommand-lineoption.
ADITAblockelementwhichsupportsallflaggingfeatures(10)iswrappedinaelementhavingflaggingattributessuchas@color,@text-decora-tion,@change-bar-placement,etc.
ADITAinlineelementwhichsupportsallflaggingfeatures(11)iswrappedinaelementhavingflaggingattributessuchas@color,@text-deco-ration,@startImage,etc.
AnyotherDITAelementisconsiderednottosupportallflaggingfeaturesandassuch,isgivenflaggingattributeslike@ditac:flags-color,@ditac:flags-back-ground-color,@ditac:flags-font-weight,etc,ratherthanbeingwrappedinaorelement.
Moreformally,thecontentmodelofisspecifiedbytheschema/ditac.
rncRELAXNGgrammar.
Example:(10)Thatis,,,,,,,,,,,,,,,,andtheirspecializations.
(11)Thatis,,,,,,,,,,,andtheirspecializations.
Chapter11.
Extensivecustomization76XMLmindDITAConverterManualIntroduction.
.
.
UsingXMLmindDITAConverterInstallingXMLmindDITAConverter.
.
.
.
.
.
ImportantTheDITAtopicscontainedina.
ditacfilearefullypreprocessed.
WhatdoesthismeanBasicallythattheyarereadytobetransformedwithoutfurtherefforts:Conrefinclusionshavebeenprocessed.
Unspecifiedattributeshavingdefaultvalueshavebeenaddedtotheelements.
Exam-ple:aelementbecomes.
Elementsnowhavea``flat'',globallyunique,ID.
Example:the@idattributeofthiselementbecomesid="introduction__start".
The@hrefattributeof,,,,el-ementsnowpointtothe(future)outputfiles.
Example:the@hrefattributeofthiselementbecomeshref="userguide-1.
html#introduction__start".
Sometextmayhavebeenaddedtoemptyandelements.
TheelementsoftheDITAmaphavebeenconvertedtosectionsortoextraelements.
Chapter11.
Extensivecustomization77XMLmindDITAConverterManualFilteredelementshavebeenremoved.
Flaggedelementshavebeenwrappedinaelement.
Contentsoftheditac_lists.
ditac_listfileTherootelementoftheditac_lists.
ditac_listfileis.
Aelementmayhavethefollowingchildelements(inthisexactorderandinthisexactnumber):Acontainsaelementforeach.
ditacfile.
Aelementmaybeseenasthemanifestofa.
ditacfile.
Example:.
.
.
ContainsalltheDITAelementsneededtogeneratethe``titlepage''sectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedhasnotitleandnometadata(e.
g.
/,/,etc).
Example:XMLmindDITAConverterManual.
.
.
ContainsalltheinformationneededtogenerateTableofContentssectionofadocument.
Chapter11.
Extensivecustomization78XMLmindDITAConverterManualExample:.
.
.
ContainsalltheinformationneededtogeneratetheListofFiguressectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedcontainsnoelementshavingachildelement.
Example:ContainsalltheinformationneededtogeneratetheListofTablessectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedcontainsnoelementshavingachildelement.
Example:Chapter11.
Extensivecustomization79XMLmindDITAConverterManualContainsalltheinformationneededtogeneratetheListofExamplessectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedcontainsnoelementshavingachildelement.
Example:.
.
.
ContainsalltheinformationneededtogeneratetheListofExamplessectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedcontainsnoelementshavingachildelement.
Example:Thisisashortdescriptionofthefirstequation.
ItshouldbedisplayedintheListofEquations.
.
.
.
ContainsalltheinformationneededtogeneratetheIndexsectionofadocument.
ThiselementexistsbutisemptyiftheDITAdocumentbeingconvertedcontainsnoelements.
Example:Chapter11.
Extensivecustomization80XMLmindDITAConverterManual.
.
.
.
.
.
Moreformally,thecontentmodelofisspecifiedbytheschema/ditac_lists.
rncRELAXNGgrammar.
Currentlytheditac_lists.
ditac_listfileisusedtogenerate:the``titlepage''sectionofadocument;theTableofContentssectionofadocument;theListofFigures,ListofTables,ListofExamples,ListofEquationssectionsofadocument;theIndexsectionofadocument;thenavigationiconsinamulti-pageHTMLdocument;allthefiles(project.
hhp,toc.
hhc,etc)requiredbytheHTMLHelpsystem;allthefiles(jhelpset.
hs,jhelpmap.
jhm,etc)requiredbytheJavaHelpsystem.
Chapter11.
Extensivecustomization81XMLmindDITAConverterManualPartIII.
EmbeddingXMLmindDITAConverterinaJavaapplicationPartIII.
EmbeddingXMLmindDITAConverterinaJavaapplication82XMLmindDITAConverterManualChapter12.
High-levelmethod:embeddingcom.
xmlmind.
ditac.
convert.
ConverterQuickandeasyembedding:embedcom.
xmlmind.
ditac.
convert.
Converter,theJavaclasswhichisusedtoimplementtheditaccommand-lineutility.
Converteristheobjectwhichisatthecoreoftheditaccommand-lineutility.
Itsrunmethodacceptsthesamestringargumentsastheditaccommand-lineutility.
ThefullsourcecodeoftheEmbed1sampleisfoundinEmbed1.
java.
1.
CreatetheConverter.
StyleSheetCachecache=newStyleSheetCache();Consoleconsole=newConsole(){publicvoidshowMessage(Stringmessage,MessageTypemessageType){System.
err.
println(message);}};Converterconverter=newConverter(cache,console);StyleSheetCacheisasimplecachefortheditacXSLT2.
0stylesheets.
Itisathread-safeobjectwhichisintendedtobesharedbyseveralConverters.
UnlikeStyleSheetCache,Converterisnotthread-safe.
EachthreadmustownitsConverter.
However,therunmethodofaConvertermaybeinvokedseveraltimes.
Consoleisaverysimpleinterface.
ImplementingthisinterfaceallowstodowhateveryouwantwiththemessagesreportedbyaConverter.
2.
ConfiguretheConverter.
if(!
converter.
registerFOP("/opt/fop/fop")){return1;}ThereareseveralmethodswhichmaybeusedtoregisteranXSL-FOprocessorwithaConverter.
Fromhigh-levelonestolow-levelones,thesemethodsare:registerFOP,registerXEP,registerAHF,registerXFC,registerExternalFOConverter,registerFOConverter.
3.
Invoketherunmethod.
String[]args={"-v","-p","number","all",outFile.
getPath(),inFile.
getPath(),};returnconverter.
run(args);Therunmethodreturns0iftheconversionissuccessfulandanintegergreaterthan0otherwise.
Whentheconversionfails,errorsmessagesaredisplayedontheConsole.
Chapter12.
High-levelmethod:embeddingcom.
xmlmind.
ditac.
convert.
Converter83XMLmindDITAConverterManualEnvironmentrequiredforrunningthiskindofembeddingAside".
jar"fileslikeditac.
jar,resolver.
jar,saxon9.
jar,etc,whicharealllistedinditac_in-stall_dir/doc/manual/embed/build.
xml(seebelow),thiskindofembeddingalsoneedstoaccess:TheDITADTD,schemasandXMLcatalogsnormallyfoundinditac_install_dir/schema/.
TheXSLstylesheetsnormallyfoundinditac_install_dir/xsl/.
Thereforetherequirementsforrunningthiskindofembeddingare:1.
Usesystempropertyxml.
catalog.
filestopointtoditac_install_dir/schema/catalog.
xmlortoanequivalentofthisXMLcatalog.
2.
Stockditac_install_dir/schema/catalog.
xmlcontainsthefollowingentry:ThisentryisneededtofindthelocationofthedirectorycontainingtheXSLstylesheets.
MakesurethatthisentryexistsinyourXMLcatalogsandthatitpointstotheactuallocationofthedirectorycontainingtheXSLstylesheets.
CompilingandexecutingtheEmbed1sampleCompiletheEmbed1samplebyrunningantinditac_install_dir/doc/manual/embed/.
ExecutetheEmbed1samplebyrunningantembed1inditac_install_dir/doc/manual/embed/.
Thiswillconvertditac_install_dir/docsrc/manual/manual.
ditamaptoditac_install_dir/doc/manual/embed/manual.
pdf,usingApacheFOP.
NotethatEmbed1.
javacontains"hardwiredfilenames"like"/opt/fop/fop".
Thismeansthat,withoutmodifications,thissamplecannotberunfromelsewherethanditac_install_dir/doc/manual/embed/andthatyou'llalmostcertainlyneedtomodifythesourcecodeinordertospecifytheactuallocationofthefop(fop.
bat)script.
RelatedinformationChapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessorChapter12.
High-levelmethod:embeddingcom.
xmlmind.
ditac.
convert.
Converter84XMLmindDITAConverterManualChapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessorAdvancedembeddingmethod:firstinvokeapreprocessorwhichwillgenerateintermediate.
ditacfiles,theninvoketheXSLT2.
0engineinordertotransformallthese.
ditacfiles.
ThismethodconsistsinfirstinvokingthePreProcessorinordertopre-processtheDITAsourcefilesintoaditac_lists.
ditac_listsfileandoneormore.
ditacfiles;theninvokingtheSaxonXSLT2.
0engineinordertotransformallthe.
ditacfiles.
Forsomeoutputformats,PDF,RTF,etc,thefinalthirdstepconsistsininvokinganXSL-FOprocessorsuchasApacheFOPinordertoconverttheXSL-FOgeneratedbytheXSLTstylesheetstothedesiredoutputformat.
ThefullsourcecodeoftheEmbed2sampleisfoundinEmbed2.
java.
1.
InvoketheditacPreProcessortopre-processtheDITAsourcefilesintoaditac_lists.
di-tac_listsfileandoneormore.
ditacfiles.
1.
a.
CreateandconfigurethePreProcessor.
Consoleconsole=newConsole(){publicvoidshowMessage(Stringmessage,MessageTypemessageType){System.
err.
println(message);}};PreProcessorpreProc=newPreProcessor(console);preProc.
setChunking(Chunking.
SINGLE);preProc.
setMedia(Media.
SCREEN);ResourceCopierresourceCopier=newResourceCopier();resourceCopier.
parseParameters("img");preProc.
setResourceHandler(resourceCopier);Consoleisaverysimpleinterface.
ImplementingthisinterfaceallowstodowhateveryouwantwiththemessagesreportedbyaPreProcessor.
SpecifiyingpreProc.
setChunking(Chunking.
SINGLE)allowstogenerateasingleHTMLpageusingaDITAmapdesignedtogeneratemultipleHTMLpages.
APreProcessorisnotconcernedabouttheexactoutputformat.
HoweveritsbehavesdifferentlydependingonthetargetMedia.
APreProcessorhandlestoanResourceHandleralltheresourcefiles,typicallyimagefiles,referencedintheDITAsourceusingrelativeURLs.
AnResourceHandlerisreg-isteredwithaPreProcessorusingmethodsetResourceHandler.
InthecaseoftheEmbed2sample,weusethesimplestpossibleResourceHandlerwhichisResourceCopier.
1.
b.
Pre-processtheDITAsourcefiles.
URLinFileURL=null;try{inFileURL=inFile.
toURI().
toURL();}catch(MalformedURLExceptioncannotHappen){}Chapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessor85XMLmindDITAConverterManualFile[]preProcFiles=null;try{preProcFiles=preProc.
process(newURL[]{inFileURL},outFile);}catch(IOExceptione){console.
showMessage(e.
toString(),Console.
MessageType.
ERROR);}if(preProcFiles==null){returnfalse;}TheprocessmethodofaPreProcessorreturnsnullifanerrorotherthananIOExceptionhascausedthepre-processingtofail.
Whenthisisthecase,errorsmessagesaredisplayedontheConsole.
NotethataPreProcessorisnotthread-safe.
EachthreadmustownitsPreProcessor.
How-ever,theprocessmethodofaPreProcessormaybeinvokedseveraltimes.
2.
InvoketheSaxonXSLT2.
0engine,inordertotransformallthe.
ditacfiles.
NotethatthisisdoneusingthestandardJAXPAPI.
2.
a.
PassrequiredsystemparameterstotheXSLTstylesheets,inadditiontothenormal,user,pa-rameters.
StringditacListsURI="";intcount=preProcFiles.
length;for(inti=0;icls=Class.
forName("net.
sf.
saxon.
TransformerFactoryImpl");TransformerFactorytransformerFactory=(TransformerFactory)cls.
newInstance();ExtensionFunctions.
registerAll(transformerFactory);transformerFactory.
setURIResolver(uriResolver);transformerFactory.
setErrorListener(errorListener);returntransformerFactory;}CreatinganinstanceofSaxon9isabsolutelyneeded.
XMLmindDITAConverterisnotdesignedtoworkwithanyotherXSLTengine(e.
g.
theXalanXSLT1.
0engine,whichispartoftheJavaruntime).
TheditacXSLT2.
0stylesheetsmakeuseofafewXSLTextensionfunctionswritteninJava.
TheseextensionfunctionsmustberegisteredwithSaxon.
ThisisdoneusingEx-tensionFunctions.
registerAll.
2.
c.
CreateandconfigureaTransformer.
privatestaticTransformercreateTransformer(String[]params,Consoleconsole)throwsException{URIResolveruriResolver=Resolve.
createURIResolver();ErrorListenererrorListener=newConsoleErrorListener(console);TransformerFactoryfactory=createTransformerFactory(uriResolver,errorListener);FilexslFile=AppUtil.
getXSLResourceFile("xhtml/html.
xsl");Transformertransformer=factory.
newTransformer(newStreamSource(xslFile));transformer.
setURIResolver(uriResolver);transformer.
setErrorListener(errorListener);for(inti=0;iChapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessor87XMLmindDITAConverterManualHowever,staticmethodsetResolverFactoryallowstoconfigurethisthread-safeutilityclass(usedbyditacinmanyplaces)differently.
ConsoleErrorListenerisanimplementationofErrorListenerwhichdisplaysitsmes-sagesonaConsole.
AppUtil.
getXSLResourceFileisautilityfunctionusedtolocatefilesfoundintheXSLdirectory(normallyditac_install_dir/xsl/).
2.
d.
InvoketheTransformertotransformeach.
ditacfile.
for(inti=0;iThisentryisneededtofindthelocationofthedirectorycontainingtheXSLstylesheets.
MakesurethatthisentryexistsinyourXMLcatalogsandthatitpointstotheactuallocationofthedirectorycontainingtheXSLstylesheets.
CompilingandexecutingtheEmbed2sampleCompiletheEmbed2samplebyrunningantinditac_install_dir/doc/manual/embed/.
ExecutetheEmbed2samplebyrunningantembed2inditac_install_dir/doc/manual/embed/.
Thiswillconvertditac_install_dir/docsrc/manual/manual.
ditamaptosingleHTML4.
01pagedi-tac_install_dir/doc/manual/embed/manual.
html.
RelatedinformationPartII,Chapter11.
ExtensivecustomizationChapter12.
High-levelmethod:embeddingcom.
xmlmind.
ditac.
convert.
ConverterChapter13.
Low-levelmethod:embeddingcom.
xmlmind.
ditac.
preprocess.
PreProcessor89XMLmindDITAConverterManualAppendixA.
AboutDITAsupportinXMLmindDITAConverterDITA1.
3supportAsofversion3.
0,XMLmindDITAConverter(ditacforshort)fullysupportsDITA1.
3andassuch,allowstoconvertDITAdocumentsconformingtotheDITA1.
3DTD,W3CXMLSchemaorRELAXNGschema.
However,therearestilllimitations,deemedminor,andimplementationspecificitieswhicharedocumentedinAppendixC.
Infact,whenditacv2.
6+isused,DITA1.
2documentsareautomatically"upgraded"toDITA1.
3.
Thisiscausedbythefactthatthefollowingmeans"uselatestversionoftheDITADTD":.
.
.
ThisshouldnotbeaproblemasDITA1.
3isasupersetofDITA1.
2.
TechnicalcontentonlyDitaconlysupports"Technicalcontentelements".
HoweverClassificationelements(e.
g.
subjectschememaps)arestillnotsupported.
DITA1.
3RELAXNGschemaDitachasnoproblemprocessingaDITAdocumentpointingtoaRELAXNGschema,ratherthantoaDTDorW3CXMLSchema:.
.
.
Theprocessing-instructionusedintheaboveexampleisthestandardwaytoassociateadocumenttoaRELAXNGschema.
See"AssociatingSchemaswithXMLdocuments1.
0".
TheDTDToSchemafacilityTheDTDToSchemafacilitycanbeusedto"upgrade"yourdocumentsconformingtoaDITA1.
3DTDtotheequivalentDITA1.
3W3CXMLSchemaorRELAXNGschema.
Command-lineexampleshowinghowtoinvoketheDTDToSchemafacility:$java-cpditac_install_dir/lib/ditac.
jarcom.
xmlmind.
ditac.
tool.
DTDToSchema-rngMyTopic.
ditaBeforeinvokingtheDTDToSchemafacility,MyTopic.
ditacontained:AppendixA.
AboutDITAsupportinXMLmindDITAConverter90XMLmindDITAConverterManual.
.
.
AfterinvokingtheDTDToSchemafacility,MyTopic.
ditacontains:.
.
.
TheDTDToSchemafacilityisauto-documented:$java-cpditac_install_dir/lib/ditac.
jarcom.
xmlmind.
ditac.
tool.
DTDToSchemaUsage:java-cpditac.
jarcom.
xmlmind.
ditac.
tool.
DTDToSchema-rng|-xsd[in_dita_file|in_dir_containing_dita_files]+"Upgrades"specifiedDITAdocumentsconformingtoastandardDITA1.
3DTDtothecorrespondingW3CXMLschemaorRELAXNGschema.
Processesfilesordirectories.
Filesaremodifiedinplace.
Directoriesarerecursivelyprocessed.
Allthe'.
ditamap','.
dita'and'.
ditaval'filesfoundinspecifieddirectoriesareprocessed.
Options:-rngUpgradetoRELAXNGschema.
-xsdUpgradetoW3CXMLschema.
RelatedinformationAppendixC.
LimitationsandimplementationspecificitiesAppendixA.
AboutDITAsupportinXMLmindDITAConverter91XMLmindDITAConverterManualAppendixB.
LightweightDITAsupportXMLmindDITAConverterfullysupportsLightweightDITA(AKALwDITA)support,whetherXDITA(verysmallsubsetofDITAXML,plusnewandelements),HDITA(topicsandmapswritteninHTML5)orMDITAExtendedProfile(topicsandmapswritteninMarkdown).
XMLmindDITAConvertercanofcourseprocessDITAdocumentscomprisingamixofXDITA,HDITA,MDITAand(full)DITAtopicsandmaps.
You'llfindinthefollowingsectionssometemplatestostartwritingtopicsandmapsinXDITA,HDITAandMDITA.
You'llalsofindthelistofHDITAandMDITAimplementationspecificitiesandlimitations.
1.
XDITAsupportXMLmindDITAConverterfullysupportsXDITA,whichisbasicallyaverysmallsubsetofDITAXML,plusnewaudioandvideoelements.
TemplateofanXDITAtopic(lwdita_templates/xdita_topic.
dita):TemplateofanXDITAmap(lwdita_templates/xdita_map.
dita):2.
HDITAsupportXMLmindDITAConverterfullysupportsHDITA,whichspecifieshowtowriteDITAtopicsandmapsinHTML5.
AppendixB.
LightweightDITAsupport92XMLmindDITAConverterManualImportantOnlyXHTML5,thatis,theXMLsyntaxofHTML5,issupported.
PlainHTML5isnotsupported.
Inpractice,thismeansthatalltagsmustbeclosed(e.
g.
andnot),allattrib-utesmusthaveaquotedvalue(e.
g.
controls=""andnotcontrols)andthatelementslikeheadandbodymaynotbeomitted.
TemplateofanHDITAtopic(lwdita_templates/hdita_topic.
html):TopictitlehereTopictitlehereShortdescriptionhere.
Topicbodystartshere.
TemplateofanHDITAmap(lwdita_templates/hdita_map.
html):MaptitlehereMaptitlehereAppendixB.
LightweightDITAsupport93XMLmindDITAConverterManualImplementationspecificitiesAddingattributedata-class="concept"tothetop-levelarticleelementmaybeusedtogenerateaDITAconceptratherthanaDITAtopic.
Afootnotemayberepresentedby,inadditionto.
Afootnotereferencemayberepresentedby.
Aninternallinkmaybespecifiedas.
Noticethatthereisnoneedtospecify,likeinDITAXML,or.
OnlythemetaelementshavingthefollowingnamesaretranslatedtotheirDITAequivalent(thatis,elementscontainedintheprologofaDITAtopicorthetopicmetaofaDITAmap):–audience–author–category–createdordcterms.
created(mapsto/)–keyword(mapsto/)–permissions–publisherordcterms.
publisher–resourceid–revisedordcterms.
modified(mapsto/)–sourceAmetaelementhavinganyothernameistranslatedtoDITAelementdata.
WhilemostHTML5elementsarefaithfullytranslatedtotheirDITAequivalent,–someelements(br,hr,iframe,script,etc)aresimplyignored;–someotherelementsaretranslatedtoaDITAphordivhavinganoutputclassattributere-flectingtheirHTML5origin.
Example1:elementsmallistranslatedtoDITA.
Example2:anh1elementotherthantheveryfirstone(specifyingthetitleofthetopic)istranslatedtoDITA.
Example3:nestedsectionsaretranslatedtoDITA.
LimitationsOnlyXHTML5,thatis,theXMLsyntaxofHTML5,issupported.
PlainHTML5isnotsupported.
UsingattributerowspanintdorthelementswillgenerallycauseanincorrectDITAtabletobegenerated.
3.
MDITAsupportXMLmindDITAConverterfullysupportsMDITA,whichspecifieshowtowriteDITAtopicsandmapsinMarkdown.
AppendixB.
LightweightDITAsupport94XMLmindDITAConverterManualTemplateofanMDITAtopiclwdita_templates/mdita_topic.
md:---id:---#TopictitlehereShortdescriptionhere.
Topicbodystartshere.
TemplateofanMDITAmaplwdita_templates/mdita_map.
md:#Maptitlehere{.
map}Noticethe{.
map}classattributeaddedtothetitleofthemap.
Withoutit,theabovetemplatewouldbetranslatedtoaDITAtopic.
ImplementationspecificitiesTheencodingofanMDITAfileis,bydefault,thesystemencoding(e.
g.
window-1252onaWesternPC).
IfyouwanttoexplicitlyspecifytheencodingofanMDITAfile,pleasesaveyourfilewithaUTF-8orUTF-16BOM(ByteOrderMark)oraddanencodingdirectiveinsideacommentanywhereatthebeginningofyourfile.
Example:coding:iso-8859-1-*--->Heading=======##Sub-headingParagraphsareseparatedbyablankline.
TheaboveexampleshouldworkfinebecauseditacunderstandstheGNUEmacsfilevariablecalledcoding.
Addinga{.
concept}classattributetothetitleofanMDITAtopicmaybeusedtogenerateaDITAconceptratherthanaDITAtopic.
Outofthebox,ditacsupportstheso-calledExtendedProfile.
ThisExtendedProfilemaybecustomizedbythemeansof-pload.
mdita.
XXXparameters.
Theseload.
mdita.
XXXparametersaredocumentedbelow.
AppendixB.
LightweightDITAsupport95XMLmindDITAConverterManualLimitationsWithouta{.
map}classattributeaddedtothetitleofanMDITAmap,thismapisconfusedwithatopic.
load.
mdita.
XXXparametersParameter-pload.
mdita.
extended-profiletrueisimplicitelypassedtoditac.
Thisparameterissimplyashorthandfor:-pload.
mdita.
abbreviationtrue-pload.
mdita.
admonitiontrue-pload.
mdita.
attributestrue-pload.
mdita.
definitiontrue-pload.
mdita.
footnotestrue-pload.
mdita.
gfm-strikethroughtrue-pload.
mdita.
instrue-pload.
mdita.
superscripttrue-pload.
mdita.
tablestrue-pload.
mdita.
typographictrue-pload.
mdita.
yaml-front-mattertruewhereabbreviation,admonition,attributes,etc,areallMarkdownextensions,documentedinMarkdownextensions.
Ifforexample,youdon'tlikethestockExtendedProfileandprefertouseasimplerone,plustheautolinkMarkdownextension(12),thenpass:-pload.
mdita.
core-profiletrue-pload.
mdita.
autolinktruetoditac.
Parameter-pload.
mdita.
core-profiletrueissimplyashorthandfor:-pload.
mdita.
gfm-strikethroughtrue-pload.
mdita.
superscripttrue-pload.
mdita.
tablestrue-pload.
mdita.
yaml-front-mattertrue3.
1.
MarkdownextensionsAbbreviationsConvertsplaintextabbreviations(e.
g.
IBM)toelements.
ThisMarkdownsyntaxextension,whichispartoftheMDITAExtendedProfile,isenabledbydefault.
Inordertodisableit,passparameter-pload.
mdita.
abbreviationfalsetoditac.
Example:TheHTMLspecificationismaintainedbytheW3C.
(12)TurnsplaintextURLsandemailaddressesintoelements.
AppendixB.
LightweightDITAsupport96XMLmindDITAConverterManual*[HTML]:HyperTextMarkupLanguage*[W3C]:WorldWideWebConsortiumisconvertedto:TheHTMLspecificationismaintainedbytheW3C.
whichisrenderedas:TheHTMLspecificationismaintainedbytheW3C.
AdmonitionsSyntaxforcreatingadmonitionssuchasnotes,tips,warnings,etc.
ThisMarkdownsyntaxextension,whichispartoftheMDITAExtendedProfile,isenabledbydefault.
Inordertodisableit,passparameter-pload.
mdita.
admonitionfalsetoditac.
Afterthe"!
!
!
"tag,theadmonitiontypemustbeoneof"note","attention","caution","danger","fastpath","important","notice","remember","restriction","tip","trouble","warning".
Anoteexamplenothavingatitle:!
!
!
note""Supportislimitedtobugreports.
isconvertedto:Supportislimitedtobugreports.
whichisrenderedas:NoteSupportislimitedtobugreports.
Atipexamplehavingatitle:!
!
!
tip"HowdoyoudoahardrebootonaniPad"Pressandholdboththe**Home**and**Power**buttonsuntilyouriPad®reboots.
YoucanreleasebothbuttonswhenyouseeApple®logo.
isconvertedto:HowdoyoudoahardrebootonaniPad