Specializationistheprocess bywhichnew designsarecreatedbased offexistingdesigns, allowingnew kindsofcontenttobeprocessedusingexistingprocessingrules.
Specializationprovidesa waytoreconciletheneedsforcentralized managementofmajorarchitecture anddesignwith theneedsforlocalizedmanagementofgroup-specificandcontent-specificguidelines andbehaviors.Specializationallowsmultipledefinitions ofcontentandoutputtoco-exist,related througha hierarchyoftypesand transforms.Thishierarchyletsgeneraltransformsknowhow todeal withnew,specificcontent,and itletsspecializedtransformsreuselogicfromthegeneraltransforms.Asa result,anycontent canbe processedbyanytransform,aslongasbothcontentand transformare
specialization-compliant,andpart ofthesamehierarchy.Specializersgetthebenefitofspecificsolutions, butalsoget thebenefitofcommonstandardsand sharedresources.
Content Processing Result
Unspecialized Unspecialized Baseprocessing,expectedoutput
Unspecialized Specialized Baseprocessing,specializedoverrides
areignored,expectedoutput
Specialized Unspecialized Baseprocessing,specializedcontent
treatedasgeneral,outputmayfall shortofexpectations
Specialized Specialized Specializedprocessing,expected
output
Specialized Differentlyspecialized Somespecializedprocessing,
specializedcontenttreatedasnearest commondenominator,outputmay fallshortofexpectations
Thefollowingtopicsprovideanoverviewofspecialization,somerecommendationsforuse,and detailed rulesforitsmechanisms.
What is specialization?
Specializationallowsyoutodefinenew kindsof information(newstructuraltypesornewdomains of information),whilereusingasmuchof existingdesignand codeaspossible,and minimizingor eliminatingthecosts ofinterchange,migration, andmaintenance.
Specializationisusedwhennew structuraltypesornewdomains areneeded.DITAspecializationcanbe usedwhenyouwanttomakechangestoyour designforthesake ofincreasedconsistency or
descriptivenessorhaveextremelyspecific needsforoutputthatcannotbeaddressedusingthecurrent datamodel.Specializationisnotrecommended forsimplycreatingdifferentoutputtypesasDITA documentsmaybetransformedtodifferentoutputs withoutresortingto specialization(see
“Customization”onpage42).
Therearetwokindsofspecializationhierarchy:oneforstructuraltypes(withtopicormapat theroot) andonefordomains (withelementsintopicormapattheirroot).Structuraltypesdefinetopicormap structures,suchasconceptortaskorreference,whichoftenapplyacrosssubjectareas(forexample,a userinterfacetask andaprogramming taskmaybothconsistofa seriesofsteps). Domainsdefine markupforaparticularinformationdomainorsubjectarea,suchasprogramming,orhardware.Eachof themrepresentan “isa”hierarchy,inobject-orientedterms,with eachstructuraltypeordomainbeinga
27
subclassofitsparent.Forexample,a specializationof taskisstill atask;anda specializationoftheuser interfacedomainisstillpartof theuser interfacedomain.
Usespecializationwhenyouare dealingwith newsemantics(new,meaningfulcategoriesof information, eitherintheformofnew structuraltypesornewdomains).Thenewsemantics canbe encodedaspartof aspecializationhierarchy,thatallowsthemtobe transformedbacktomoregeneral equivalents,andalso ensuresthatthespecializedcontent canbe processedbyexistingtransforms.
Why specialization?
Specializationcanhavedramaticbenefitsforthedevelopment ofnewdocumentarchitectures.
Amongthebenefits:
v Noneedtoreinventthebasevocabulary-Createamodulein1/2 daywith 10linesvs.6 monthswith 100soflines;automaticallypick upchangestothebase
v Noimpactfromotherdesignsthatcustomize fordifferentpurposes-Avoidenormous, kitchen-sink vocabularies;Pluginthemodulesforyour requirements
v Interoperabilityatthebasetype-Guaranteed reversionfromspecialtobase v
Reusabletypehierarchies-Shareunderstandingofinformationacrossgroups,savingtimeand presentinga consistentpicturetocustomers
v Outputtailoredtocustomersand information-Morespecificsearch,filtering,andreusethatis designedforyour customersandinformationnotjustthecommondenominator
v Consistency-Bothwith basestandardsandwithin yourinformationset
v Learningsupportfornewwriters -Insteadoflearningstandardmarkupplusspecificwaystoapply themarkup,writersget specificmarkupwith guidelinesbuiltin
v Explicitsupport ofdifferentproductarchitecturalrequirements-Requirementsofdifferentproducts andarchitecturescanbesupportedandenforced,rather thansuggestedandmonitored byeditorial staff
Structural versus domain specialization
Structuralspecializationdefinesnew typesofstructuredinformation,suchasnew topictypesornew maptypes. Domainspecializationcreates newmarkupthatcanbeusefulinmultiplestructural types, suchasnew kindsofkeywords,tables,orlists.
Structuraltypesdefinestructuresformodulesofinformation,suchasconcept ortaskorreference,which oftenapplyacrosssubjectareas(forexample,a userinterfacetaskand aprogramming taskmayboth consistofa seriesofsteps). Whennew elementsareintroducedthroughstructural specialization,the elementsthatcontainthenew elementsmustbe specializedaswell;andthenewcontainerelements musthavetheircontainersspecializedinturn,allthewaytotherootelementforthemodule(for example,the<topic> elementor<map>element).
Domainstypicallydefinemarkupforaparticulardomainorsubjectarea,suchasprogramming,or hardware.Domainelementsbecomeavailable wherevertheirancestorelementsareallowedoncethe domainsareintegrated withthestructuralspecializationsina documenttype.
Bothstructuralspecializationhierarchiesand domainspecializationhierarchiesare“isa”hierarchies, in object-orientedterms,with eachstructuraltypeordomainbeinga subclassof itsparent.Forexample,a specializationoftaskisstill atask;anda specializationof theprogramming domainisstill concerned withprogramming.
Structuralanddomainhierarchiesmustsharea commonbasemoduleinordertobe integratedtogether.
Forexample,domainsforuseacrosstopictypesmust ultimatelybespecializedoffofelementsin
<topic>.
Withtheexceptionof thecommonbase module,a domaincannotbespecializedfroma structuraltype.
Forexample,adomain cannotbe specializedfromelementsin<task>,onlyfromtherootstructural modulesfor<topic>or<map>.Thisruleensuresthatdomains canbe integratedanddocumenttypes canbegeneralizedpredictably. TherulemayberelaxedinfutureversionsofDITAifa mechanismis addedfortrackingdependenciesbetweenstructuraland domainspecializationsinusebya document type.
Elementscreatedbyspecializationarescoped bythenameofthestructuraltypeordomain inwhichthey weredeclared. Forstructuraltypes, thenameisthesameastherootelement: forexample,taskisthe nameofthestructural typewhoserootelementis<task>.Fordomains,thenameisnotshared withany element,butisassignedbythedeveloperofthespecialization.By convention,domainnamesendwith
″-d″and arekeptshort;forexample,ui-dfortheuserinterface domainandpr-dfortheprogramming domain.
Limits of specialization
Therearetimeswhenanew structuralordomaintype appearsnottofitintotheexistinghierarchy, basedonthesemanticsoftheexistingtypesand therestrictions ofthespecializationprocess. Inthese casesthereare avarietyofoptionstoconsider.
ThebasicspecializationmechanismusedbytheDITAdocumenttypescanalso beusedfornon-DITA documenttypesinorderto providethesamere-use,specialization,andinteroperationbenefitsthatone cangetfromtheDITAdocumenttypes, butrestrictedtothespecificdomainwithin whichthenew documenttypesapply. NotethatevenifoneusestheDITA-definedtypesasa startingpoint,anychange tothosebasetypesnotaccomplishedthroughspecializationdefinesa completelynewdocumenttype thathasnomeaningfulornormative relationshiptotheDITAdocumenttypesandcannotbeconsidered inanyway tobea conformingDITAapplication.Inotherwords,theuseofDITAspecializationfrom non-DITAbasetypesdoesnotproduceDITA-compliantdocumenttypes.
However,giventhesubstantialbenefitsofbuildingfromthecommonDITAbaseclasses(includingthe abilitytogeneralizetoacommon format,useof standards-complianttoolsand processes,and reuseof contentacrossdocumenttypesthrough DITAmapsandconref) thereare sometechniquestoconsider beforecompletedeparturefromtheDITAcontent architecture.
Specializefromgenericelements
Thefirstoption toconsideristochoosemoregenericbase elementsfromtheavailable set.Forexample, ifyouwanttocreatea newkindof listbutcannotusefullydosospecializingfrom<ul>,<ol>, <sl>,or
<dl>,youcancreatea newset oflistelementsbyspecializingnested<ph>elements.Thisnew list structurewillnotbe semanticallytiedtotheotherlists byancestry,andsowillrequirespecialized processingtoreceiveappropriateoutputstyling.However, itwillremainavalidDITAspecialization, withthestandardsupportforgeneralization,content referencing,conditionalprocessing,and soforth.
Thefollowingbaseelementsin<topic>aregeneric enoughtosupportalmost anystructurallyvalid specialization:
topic anycontentunitthathasatitleandassociatedcontent section
anynon-nestingdivisionofcontentwithin atopic,titledornot p anynon-titledblockofcontent belowthesectionlevel
fig anytitledblockofcontentbelowthesectionlevel ul,ol,dl,sl,simpletable
anystructuredblockof contentthatconsistsof listeditemsinoneormorecolumns ph anydivisionofcontentbelow theparagraph level
Chapter4.DITAspecialization 29
keyword
anynon-nestingdivisionofcontentbelow theparagraphlevel
Youshouldalways specializefromthesemanticallyclosestmatchwheneverpossible.Whensome structuralrequirementforcesyoutopicka moregeneralancestor,pleaseinform thetechnicalcommittee:
overtimea richerset ofgenericelementsshouldbecomeavailable.
Customizedsubsetdocumenttypesforauthoring
DITAmarkupisorganizedinto domainandtopictypemodules sothatauthoringgroupscaneasilyselect themarkupsubset theyrequirebycreatinganew documenttype shell.However, whenanauthoring grouprequiresasubsetofmarkuprulesthatdoesnotfollowtheboundariesofthetypemodules (for example,globalremovalofcertainattributes orelements),youcanifnecessarycreatea customized documenttypeforthesakeofenforcingtheserulesatauthoringtime,aslongasthedocumenttypesare validatedusingastandards-compliantdocumenttype atprocessingtime.
Acustomizedsubsetdocumenttypeshouldbe createdwithouteditingofthetypemodules.The
documenttypeshellcanoverrideentitiesinthemodulefiles,includingattributes andcontentmodels,by providinganew definitionoftheentity beforeimportingthemodulefiles.
CustomizedsubsetdocumenttypesarenotcompliantwiththeDITAstandard,andmaynotbesupported bystandards-complianttools.However,customized subsetdocumenttypescanhelp limitthequantity andmitigatetheconsequencesofnon-standard designinacustomized implementation.
Mapfrom customizeddocumenttypetoDITAduringpreprocessing
Whilespecializationcanbeusedtoadaptdocumenttypesformanydifferentauthoringpurposes,there aresomeauthoringrequirementsthatcannotbemetthrough specialization-particularlysplitting or renamingattributes,and simplerenamingofelements.Inthese cases,wherethenew documenttype can bestraightforwardly andreliablytransformedtoastandarddocumenttype,theauthoringgroup maybe bestserved bya customizeddocumenttypethatistransformedtoastandarddocumenttype aspart of thepublishingpipeline.Forexample,ifan authoringgrouprequiresadditionalmetadataattributes,and findsauthoringmultiplemetadataaxesinoneattribute(otherprops)unusable,thedocumenttype could becustomized toaddmetadataattributesand thenpreprocessed topushthosevaluesintootherprops beforefeedingthedocumentsintoa standardpublishing process.
Acustomizeddocumenttypeshouldbecreated withouteditingofthetypemodules.Thedocumenttype shellcanoverrideentitiesinthemodule files,includingattributesand contentmodels,byproviding a newdefinitionoftheentitybefore importingthetype modulefiles.
CustomizeddocumenttypesarenotcompliantwiththeDITAstandard,andwillnotbe supportedby standards-complianttools.Preprocessingcanensurecompatibilitywith existingpublishing processes,but doesnotensurecompatibility withDITA-supportingauthoringtoolsorcontentmanagementsystems.
However,whenanimplementationisbeingheavilycustomized inanycase, acustomized document typescanhelp isolateand controltheimplicationsofnon-standarddesignina customized
implementation.
Specialization in content
Specializationisexpressedin contentthroughtheuseof twoattributes:theclassattributeandthe domainattribute.Thesearenottypicallypresentinthedocumentinstance,but areprovidedbydefault valuesexpressedina DTDorschema.
Why specialization in content?
Specializationattributeslet processesand toolsknowwhatsetofrulesyourmarkupconforms to.This allowsreuseoftoolsand processesfor unfamiliarmarkup.
The class attribute
EachelementdeclaredintheDITAarchitecture hasa classattribute.Thisattributeprovidesa mapping betweentheelement’s currentnameanditsmoregeneralequivalents.Themore specializedtheelement type,thelongeritsclassattributevalue.
Forexample,theclassattributeforthetasktopictype’sstep elementis:
<!ATTLIST step class CDATA "- topic/li task/step ">
Thistellsus thatthestep elementisequivalenttothelielementina generictopic.Italsotellsus that stepisequivalenttoastep inatasktopic,whichwealreadyknew,butit’sworthnotingthis inthe attributebecauseitenablesround-tripmigration betweenupper levelandlowerleveltypeswithoutloss ofinformation.Forexample,ifa userrunsa″generalize″transformthatmapsall elementstotheirfirst classvalue,butpreservestheir contentandattributevalues,then theusercanfollowit upwitha
″specialize″transformthatmapsallelementstotheirlastclassvalue (preservingcontentandattribute values),and provideafullroundtrip forallcontentbetweenthetwodocumenttypes,usingnothingbut twogeneric transformsand theinformationin theclassattribute.
Theclassattributetellsaprocessor whatgeneralclassesofelementsthecurrentelementbelongsto.It’s somethinglikeanarchitecturalformsattribute,exceptthatitcontainsmultiple mappingsina single attribute,insteadof onemappingperattribute.Also,DITAscopesvaluesbymoduletype(forexample topictype,domaintype,ormaptype)insteadofdocumenttype,whichletsuscombinemultipletopic typesin asingledocumentwithoutcomplicatingtransformlogic.
Combiningthemappings intoasingleattributegivesusthefollowingbenefits:
v preservationofsequence: youcantellbylooking attheorderofvalueswhichoneisthemostgeneral andwhichoneisthemostspecific.Thisisespeciallyimportantfor ″specializing″transforms,where youcanapplya generalrulethatsays:if theelementdoesn’thaveamappingtothetargettopictype, simplyusethelastvalueoftheclassattribute(and assumethatthespecializedtopictype isreusing somegeneralelementdeclarations,whichonlyhavemappings forthelevelatwhichtheywere declared).
v mappingpersistencethroughmigration:whenyoumigratetoa higher-levelelement,youcanpreserve itsmorespecializedhistoryintheclassattribute.Ifyouweredeclaringa newattributeforeachnew mapping(asinarchitecturalforms),then whenyoumigrated tothehigher-leveltypethedeclaration forthemappingattributewoulddisappear,and roundtrippingwouldbeconsiderablymore
problematic.
Class attribute syntax
Theclassattributehasa particularsyntaxthatmust befollowedforittobe processedcorrectly.
Everyelementmust haveaclassattribute.Theclassattributestartswitha ″-″ifitisdeclaredina structuralmodule,ora″+″ifitisdeclaredinadomainmodule.Afterthestartingtokenareoneormore blank-delimitedvalues,ending witha blank.Eachvalue hastwoparts:thefirstpart identifiesa module package,forexamplea topictypeordomainpackagename, andthesecondpart(after a/)identifies an elementtype. Structuralnamesare takenfromtherootelementforthetopictype ormaptype.Domain namesaredefinedinthedomainpackage.
Typically,theclassattributevalue shouldbe declaredasa defaultattributevalueintheDTDorschema ratherthandirectlyinthedocumentinstance.Theclassattributeshouldnotbe modifiedbytheauthor.
Chapter4.DITAspecialization 31
WhentheclassattributeisdeclaredintheDTD orschema,itmust bedeclaredwitha defaultvalue.In ordertosupportgeneralizationround-tripping(generalizingspecializedcontentintoageneric formand thenreturningittothespecializedform) thedefaultvalue mustnotbe fixed.Thisallowsthe
generalizationprocess tooverwritethedefaultvaluesinageneraldocumenttype withspecializedvalues takenfromthedocumentbeinggeneralized.
Whena specializedtype declaresnewelements,itmustprovidea classattributeforthenewelement.
Theclassattributemustinclude amappingforeverystructural typeordomaininthespecializedtype’s ancestry,eventhoseinwhichnoelementrenamingoccurred.Themappingshouldstart withthevalue forthebasetype(forexampletopicormap), andfinish withthecurrentelementtype.
Intermediatevaluesarenecessarysothatgeneralizingandspecializingtransformscanmapvaluessimply andaccurately.For example,if task/kwdwasmissingasa value,anda userdecidedtogeneralizethis guitaskuptoatasktopic,thenthetransformwouldhavetoguesswhethertomaptokwd(appropriate iftaskismoregeneralthanguitask,whichitis)orleaveaswindowname(appropriateiftaskweremore specialized,whichitisn’t).By alwaysprovidingmappings formoregeneralvalues,wecanthen apply thesimplerulethatmissingmappingsmust bydefaultbe tomorespecializedvaluesthantheoneweare generalizingto,whichmeansthelast valueinthelistisappropriate.For example,whenspecializingto
<task>,ifa<p> elementhasnotargetvaluefor <task>,wecansafelyassumethat<p>doesnot specializefrom<task>and shouldnotbe generalized.
Whilethis exampleistrivial,morecomplicatedhierarchies(say,fivelevelsdeep,withrenamingoccurring attwoandfouronly)makeexplicitintermediate valuesessential.
Aspecializedtypedoesnotneedtochangetheclassattributeforelementsthatitdoesnotspecialize,but simplyreusesbyreferencefrommoregenericlevels.Forexample,sincetask,bctask,andguitaskusethe pelementwithoutspecializingit,they don’tneedtodeclaremappings forit.
Aspecializedtypeonlydeclaresclassattributesfortheelementsthatituniquely declares.Itdoesnot needtodeclareclassattributesforelementsthatitreusesorinherits.
The domains attribute
Thedomainsattributeliststhenamesofthedomainsinusebythecurrentdocumenttype,and the
Thedomainsattributeliststhenamesofthedomainsinusebythecurrentdocumenttype,and the