OASIS Darwin Information Typing Architecture (DITA) Architectural Specification v1.0

(1)

Dita-v1.0-spec-os-ArchitecturalSpecification.pdf 09 May 2005

OASIS Darwin Information Typing Architecture (DITA) Architectural Specification v1.0

OASIS Standard, 09 May 2005

Document Identifier:

dita-v1.0-spec-os-ArchitecturalSpecification.pdf Location:

This Version: http://docs.oasis-open.org/dita/v1.0/dita-v1.0-spec-os-ArchitecturalSpecification.pdf

Technical Committee:

OASIS Darwin Information Typing Architecture (DITA) TC Chair(s):

Don Day, IBM Editor(s):

Michael Priestley, IBM JoAnn Hackos

Related work:

This specification replaces or supercedes:

• none

This specification is related to:

• none

Abstract:

The Darwin Information Typing Architecture (DITA) specification defines both a) a set of document types for authoring and organizing topic-oriented information; and b) a set of

mechanisms for combining and extending document types using a process called specialization.

The specification consists of:

• The DTDs and schemas that define DITA markup for the base DITA document types, as well as catalog files. While the DTDs and schemas should define the same DITA elements, the DTDs are normative if there is ever any discrepency.

• The language reference that provides explanations for each element in the base DITA document types

• This document, which comes in three parts:

– An introduction, which provides background concepts and an overview of the architecture

– The DITA markup specification, which provides an overview of DITA’s base document types

– The DITA specialization specification, which provides details of the mechanisms DITA provides for defining and extending DITA document types.

(2)

This document is part of the technical specification for the DITA architecture. While the

specification does contain some introductory information, it is not intended as an introduction to DITA nor as a users guide. The intended audience of this specification consists of implementers of the DITA standard, including tool developers and specializers.

Status:

This document was last revised or approved by the Darwin Information Typing Architecture (DITA) TC on the above date. The level of approval is also listed above. Check the current location noted above for possible later revisions of this document. This document is updated periodically on no particular schedule.

Technical Committee members should send comments on this specification to the Technical Committee’s email list. Others should send comments to the Technical Committee by using the

“Send A Comment” button on the Technical Committee’s web page at www.oasis- open.org/committees/dita.

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the Technical Committee web page (www.oasis- open.org/committees/dita/ipr.php.

The non-normative errata page for this specification is located at www.oasis- open.org/committees/dita.

(3)

Dita-v1.0-spec-os-ArchitecturalSpecification.pdf 09 May 2005

Notices

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it

represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS President.

OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this

specification. Please address the information to the OASIS President.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

(4)

Chapter 1. About the DITA Specification

TheDarwinInformationTypingArchitecture(DITA) specificationdefinesbotha)aset ofdocumenttypes forauthoringand organizingtopic-orientedinformation;and b)aset ofmechanismsforcombiningand extendingdocumenttypesusinga processcalledspecialization.

Thespecificationconsistsof:

v TheDTDsandschemasthatdefineDITAmarkupforthebaseDITAdocumenttypes, aswellascatalog files.WhiletheDTDsandschemasshoulddefinethesameDITAelements,theDTDsarenormative if thereiseveranydiscrepancy.

v Thelanguagereferencethatprovidesexplanations foreachelementinthebaseDITAdocumenttypes v Thisdocument,whichcomesinthreeparts:

– anintroduction,whichprovidesbackgroundconceptsandanoverviewofthearchitecture – theDITAmarkupspecification,whichprovidesanoverviewofDITA’sbasedocumenttypes – theDITAspecializationspecification,whichprovides detailsof themechanismsDITAprovidesfor

definingand extendingDITAdocumenttypes.

ThisdocumentispartofthetechnicalspecificationfortheDITAarchitecture.Whilethespecificationdoes containsomeintroductoryinformation,itisnotintendedasanintroductiontoDITAnorasausersguide.

Theintendedaudienceofthisspecificationconsistsofimplementers oftheDITAstandard,includingtool developersandspecializers.

Editors

MichaelPriestleyandJoAnnHackos Members

PaulAntonov

FranceBaril

RobinCover,OASIS

Don Day,IBM

StanleyDoherty,SunMicrosystems

BruceEsrig,LucentTechnologies

Yas Etessam,BlastRadius

Rob Frankland,RascalSoftware

PaulGrosso,Arbortext

JoAnnHackos

EricHixson,BMCSoftware

EliotKimber, InnodataIsogen

ChrisKravogel

Deborah Lapeyre

SeraphimLarsen,Intel

IndiLiepa,Nokia

KirstenNothstine, BMCSoftware

PaulPrescod,BlastRadius

MichaelPriestley,IBM

DavidSchell,IBM

1

(7)

KevinShaum,BMCSoftware

WendyShepperd, BMCSoftware

Jerry Smith,USDepartmentofDefense

DanaSpradley, Oracle

SharonVeach,SunMicrosystems

MikeWethington,BMCSoftware

ChristopherWong,IdiomTechnologies Additionalcontributors

PatriciaBest, SunMicrosystems

DavidBrainard,BMCSoftware

JarnoElovirta,Nokia

NancyHarrison,IBM

ErikHennum,IBM

AlanHouser

JohnHunt,IBM

Helena Jerney,Actional Corporation

ShawnJordan

Tyde Richards

BruceSesnovich,SunMicrosystems

EricSirois, IBM

ZacharyTaylor,BMCSoftware

Scott Tsao,Boeing

(8)

Chapter 2. An introduction to DITA

DITAisanarchitectureforcreating topic-oriented,information-typedcontentthatcanbe reusedand single-sourcedina varietyofways. Itisalso anarchitectureforcreatingnew topictypesand describing newinformationdomainsbased onexistingtypesand domains.

Theprocessforcreatingnew topictypesand domainsiscalledspecialization.Specializationallowsthe creationofveryspecific,targeteddocumenttypedefinitionswhilestillsharingcommonoutput

transformsanddesignrulesdevelopedfor moregeneraltypesanddomains,inmuchthesame waythat classesinan object-orientedsystemcaninheritmethodsofancestorclasses.

DITAtopics areXMLconforming.Assuch,they arereadilyviewed,edited,and validatedwith standard XMLtools,althoughsomefeaturessuchascontentreferencingandspecializationmaybenefitfrom customizedsupport.

Definitions and background concepts

Thefollowingtermshavespecificmeanings inDITAwhichshouldbeunderstoodbeforereadingeither theDITAmarkupspecificationortheDITAspecializationspecification.

Basic concepts

ThefollowingarebasicconceptsusedinDITA.

“Whataretopics?”onpage7

Atopicisaunitofinformationwith atitleandcontent,shortenoughtobe specifictoasingle subject oranswera singlequestion,butlongenoughtomakesenseonitsownand beauthoredasa unit.

“Whataremaps?”onpage14

DITAmapsaredocumentsthatcollectand organizereferencestoDITAtopics toindicatethe relationshipsamongthetopics.They canalsoserveasoutlinesortablesof contentsforDITA deliverablesand asbuildmanifestsforDITAprojects.

“Whatisspecialization?”onpage27

Specialization allowsyoutodefinenewkindsofinformation(newstructural typesornew domainsof information),whilereusingasmuchofexistingdesignandcodeaspossible,andminimizingor eliminatingthecostsofinterchange,migration,andmaintenance.

“Structural versusdomainspecialization”onpage28

Structuralspecializationdefinesnewtypesofstructuredinformation,suchasnewtopictypesornew maptypes.Domainspecializationcreatesnewmarkupthatcanbeusefulinmultiple structuraltypes, suchasnewkindsofkeywords,tables, orlists.

“Integration”onpage35

Eachdomainspecializationorstructuralspecializationhasitsown designmodule.Thesemodulescan be combinedtocreatemanydifferentdocumenttypes.Theprocess ofcreatinganew documenttype froma specificcombinationofmodules iscalled integration.

“Customization”onpage42

Whenyoujustneeda differenceinoutput,youcanuseDITAcustomizationtooverridethedefault outputwithoutaffectingportabilityorinterchange,and withoutinvolvingspecialization.

“Generalization”onpage33

Specializedcontentcanbe generalizedtoanyancestor type.Thegeneralizationprocess canpreserve informationabouttheformerlevelofspecializationto allowround-tripping betweenspecializedand unspecializedformsofthesamecontent.

3

(9)

Terminology

DITAusesa numberoftermsinparticularoruniqueways. Withinthescopeofthisspecification,the followingtermsareusedwhentalking aboutDITAmodels,DITAdeclarations,andDITAinstances.

Model terminology

DITAcanbe understoodat thelevelofanabstractmodelwithoutreferencetoparticularDTDs,schemas, oractualXMLdocuments.WhendiscussingDITAconceptsatthislevel, thefollowingterminologyis used.

Elementtype

Definesthestructureandsemantics forafragmentofcontent.

Specializedelementtype

Definesanelementtypeasasemanticrefinementofanotherelementtype.Thecontentallowed bythespecializedelementtype mustbea subsetoforidenticaltothecontentallowedbythe originalelementtype.

Topictype

Anelementtypethatdefinesacompleteunitofcontent.Thetopictypeprovides therootelement forthetopic and,throughcontainedelementtypes,substructureforthetopicinstances. Theroot elementofthetopictype isnotnecessarilythesameastherootelementofadocumenttype:

documenttypesmaynestmultiple topictypes,and mayalsodeclarenon-DITAwrapperelements astherootelementforcompatibilitywithotherprocesses.

Maptype

Anelementtypethatdefinesaset ofrelationshipsfortopicinstances. Themaptype providesthe rootelementand,through containedelementtypes,substructureforthemapinstances.Themap substructureprovideshierarchy,group,andmatrixorganizationofreferencestotopicinstances.

Structuraltype

Atopic typeormaptype.

Domain

Aset ofelementsthatsupporta specificsubjectarea.Elementsinadomaincanbeintegrated withtopicormaptypestoenhancetheirsemanticsupportforparticularkindsofcontent.For example,thestructural type<topic>declaresthe<keyword>element; whenintegratedwitha domainfordescribinguserinterfaces, newkeywordspecializations (suchas<wintitle>)become availablewherever<keyword>wasallowed intheoriginalstructuraltype.

Documenttype

Thefullset ofelementtypesdefinedinthemodulesthatareintegratedbythedocumenttype shell.ADITAdocumenttypemaysupport authoringmultiple topictypesormultiple maptypes, butnotamixofthetwo.The structuraltypescanbe augmentedwithelementsfromdomains.

Theterm″documenttype″isusedforcompatibilitywith existingstandards,since thisisthepoint atwhichDITA’ssetoftopic,domain,andmaptypesareassembledintoa documenttypethatis functionallyequivalenttoatraditionalnon-modularizeddocumenttype.

Declaration terminology

WhenthemodelisexpressedinaDTDorschema, thevariouselementtypesaredeclared.When referringtothesedeclarations, thefollowingterminologyisused.

Elementdeclaration

Therepresentationwithin aschematechnology(suchasDTD, XMLSchema,orRelaxNG)foran elementtype.

Typemodule

Therepresentationwithin aschematechnologyfortheelementtypesuniquelydefinedbyatopic type,maptype, ordomain.

(10)

Topicmodule

Therepresentationwithina schematechnology fortheelementtypesuniquelydefinedbyatopic type.

Mapmodule

Therepresentationwithina schematechnology fortheelementtypesuniquelydefinedbyamap type.

Structuralmodule

Atopicor mapmodule.

Domainmodule

Therepresentationwithina schematechnology fortheelementtypesuniquelydefinedbya domain.

Documenttypeshell

Therepresentationwithina schematechnology forashellthatdeclaresnoelementtypesitself butpointstoand assemblestopic,map,and domainmodules.

Documenttypedeclaration

Therepresentationwithina schematechnology foradocumenttype.The documenttype declarationincludesthedeclaration modulesassembledbythedocumentdeclarationshell.

Instance terminology

Whenactualdocuments,topics,and elementsarecreatedbasedona DITAdocumenttype,thefollowing terminologyisused.

Elementinstance

Anoccurrenceofanelementtypeina document.

Topicinstance

Anoccurrenceofatopictype inadocument.

Mapinstance

Anoccurrenceofamaptypeina document.

Structuraltypeinstance

Anoccurrenceofatopictype oramaptypeina document.

Documentinstance

Adocumentwhosemeaningand validityaredeterminedbyadocumenttypedeclaration.

Naming conventions and file extensions

Thefollowingnamingconventions andfileextensionsareinusebyDITA.

DITAtopicinstancefiles

*.xml,*.dita DITAmapinstancefiles

*.ditamap

DTDstructuralmodule files typename.mod

DTDdomainmodulefiles typenameDomain.mod typenameDomain.ent Schemastructuralmodulefiles

typenameMod.xsd typenameGrp.xsd

Chapter2.AnintroductiontoDITA 5

(11)

Schemadomainmodule files typenameDomain.xsd CSSoverridefiles

typename.css

customization-purpose.css XSLToverridefiles

typename.xsl

customization-purpose.xsl

(12)

Chapter 3. DITA markup

Thetwomainunitsof authoringinDITAaretopicsand maps.Eachcanbe extendedintonewstructural typesand domainsthrough specialization.

DITA topics

DITAtopics arethebasicunitsofDITAcontent.Eachtopicshouldbe organizedarounda singlesubject.

What are topics?

Atopicisa unitofinformationwitha titleand content,shortenoughtobespecific toasinglesubjector answerasingle question,butlongenoughtomakesenseonitsown andbe authoredasaunit.

InDITA,atopicisthebasic unitofauthoringand ofreuse.Adocumentmaycontainonetopicor

multipletopics,and adocumenttypemaysupport authoringoneormanykindsoftopics.Butregardless ofwheretheyoccur,alltopics havethesamebasic structureandcapabilities. Books,PDFfiles,Websites, andhelpsets, forexample,canall beconstructedfromthesameset ofunderlyingtopiccontent,although theremaybe sometopicsthatareuniquetoaparticulardeliverable,andtheorganizationoftopicsmay differtotakeadvantageoftheuniquecapabilitiesofeachdeliverymechanism.

Referenceinformationisinherentlytopic-oriented,since itrequiresinformationtobe modularand self-containedforthesakeofretrievability.

Topic-orientedauthoringforconceptualandtaskinformationhasitsrootsin Minimalism,aninstructional designtechniquefirstespoused byJohnCarroll.Theminimalistapproachtoinformationdesignfocusses onidentifyingthesmallestamountofinstructionthatallowsforthesuccessfulcompletionofatask,or thatprovidesbasicknowledgeofaconcept.Readers havegoals, andtheywanttoachievethosegoalsas quicklyaspossible.Generally,readersdon’twanttoread informationjustforthepleasureofreading.

Theyarereadingtolearnortodosomething.

SomeofthekeyprinciplesofMinimalismare:

v Supportactions.Letpeopleactastheylearn,and letthempursuethegoalstheywantto accomplish.

v Documenttasks,nottoolsorfunctions.

v Helpreadersanticipateandavoiderrors.

v Letreadersexplore.Theydon’tneed explainedwhattheycandiscoverforthemselves.

WhileDITA’stopic-orientedapproachhasitsrootsininstructionaldesign,thetopic-based approachcan beusefulforanyinformationthathashumanreadersanda consistentstructure.

Why topics?

Topicsarethebasisforhigh-qualityinformation.They shouldbeshortenoughtobe easilyreadable,but longenoughtomake senseontheirown.

Byorganizingcontentintotopics,authorscanachieveseveralgoalssimultaneously:

v Contentisreadableevenwhenaccessedfromanindexorsearch,notjustwhen readinsequenceas partofa chapter.Sincemostreadersdon’tread informationend-to-end,it’sgoodinformationdesignto makesureeachunitofinformationcanbe readonitsown togivejust-in-timehelp.

v Contentcanbeorganized differentlyforonline andprintpurposes.Authorscancreatetaskflowsand concepthierarchiesforonlineorientation,andstillhavea print-friendlycombinedhierarchythathelps peoplewhodowantanorganized readingflow.

7

(13)

v Contentcanbereused indifferentcollections.Sincethetopiciswritten tomakesensewhenaccessed randomly(asbysearch),it shouldalso makesensewhenincludedaspartofdifferentproduct deliverables,soauthorscanrefactorinformationasneeded, includingjustthetopicsthatapplyfor eachreusescenario.

Topicsaresmallenoughtoprovidelotsofopportunitiesforreuse,butlargeenoughtobe coherently authoredandread. WhileDITAsupportsreuse belowthetopiclevel,thisrequiresconsiderablymore thoughtand review,since topicsassembledoutofsmallerchunksoftenrequire editingto makethem flowproperly.By contrast,sincetopicsarealreadyorganized aroundasinglesubject,authorscan organizea setoftopicslogically andget anacceptableflowbetweenthem,since transitionsfromsubject tosubjectdon’tneedtobeasseamless astheexplanations withinasingle subject.

Information typing

Informationtypingisthepracticeof identifyingtypesoftopicsthatcontaindistinctkindsinformation, suchasconcepts, tasks,andreferenceinformation.Topicsthatanswerdifferentkindsofquestionscanbe categorizedasdifferentinformationtypes.The basetopictypesprovided byDITA(agenerictopic,plus concept,task,andreference)provideausablestartersetthatcanbeadoptedforimmediateauthoring.

Classifyinginformationbytype helpsauthors:

v

Designnew informationmoreeasilyandconsistently.

v Ensuretherightdesigngetsusedforthekindofinformation(retrieval-orientedstructureslike tables forreferenceinformation,simplesequencesof stepsfortaskinformation)

v Focusontasks.

v Factoroutsupportingconceptsandreferenceinformationintoothertopics,wherethey canbe readif requiredandignoredif not.

v Eliminateunimportantorredundantinformation.Identifycommonorreusable subjects.

Informationtypingispartofthegeneralauthoringapproach calledstructuredwriting,whichisused acrossthetechnicalauthoringindustrytoimproveinformationquality.Itisbasedonextensiveresearch andexperience,includingRobert Horn’sInformationMapping,andHughesAircraft’sSTOP(Sequential ThematicOrganization ofProposals).

InformationtypesinDITAareexpressedastopictypes. ThebasetopictypesprovidedbyDITAcanbe usedasa baseforfurtherspecialization.Newinformationtypesthatrequiredifferentstructuresand semanticsaredirectlysupportedbytopictypemodules,eachof whichdefinesthespecific markupand structuralrulesrequiredtodescribea particulartypeoftopic.Thesemodulescanthenbe integratedinto documenttypestosupport authoringinformation-typed topics.

Topic structure

Alltopics havethesamebasicstructure,regardlessoftopictype:title, description,prolog, andbody.

AllDITAtopicsmusthaveanID, atitle, andabody.Topicstructurescanconsistof thefollowingparts:

Topicelement

Requiredidattribute,containsallotherelements Title Thesubjectofthetopic.

Alternatetitles

Titlesspecificallyforuseinnavigationorsearch.Whennotprovided,thebase titleisusedforall contexts.

Shortdescription

Ashortdescriptionofthetopic.Usedbothintopiccontent,ingeneratedsummariesthatinclude

(14)

thetopic,andin linkstothetopic.Whileshortdescriptionsaren’trequired,theycanmakea dramaticdifferencetotheusability ofaninformationset,andshouldgenerallybeprovidedfor alltopics.

Prolog Containerforvariouskindsoftopicmetadata, suchaschangehistory,audience, product,andso on.

Body Theactualtopiccontent:paragraphs, lists,sections-whatever theinformationtype allows.

Relatedlinks

Linkstoothertopics.Whenanauthorcreates alinkaspartofa topic,thetopicbecomes

dependentontheothertopicbeingavailable.Toreducedependenciesbetweentopics andthereby increasethereusabilityofeachtopic,authorscanuseDITAmapstodefineandmanage links betweentopics, insteadofembeddinglinksdirectlyineachrelatedtopic.

Nestedtopics

Topicscanbedefinedinsideothertopics.Nestingcanresultincomplex documentsthatareless usableand lessreusable,andshouldbeusedcarefully.Itismoreoftenappropriateforreference information,whichcansupportlongerdocumentsorganized intomultipletopics forscanning andretrieval.

Topic content

Alltopics,regardlessoftopictype,buildonthesamecommonstructures.

Topicbodies

Whilealltopictypeshavethesameelementsfortitle,shortdescription, andprolog,theyeach allowdifferentcontentintheirbody.

Sectionsandexamples

Sectionsandexamples canbe containedonlybythebodyofatopic.They cannotnest.Theycan containblock-levelelementslikeparagraphs,phrase-levelelementslikeAPInames,or text.

Block-levelelements

Paragraphs,lists,andtablesarekindsof″block″elements.Asa classofcontent,theycancontain otherblocks,phrases,ortext,thoughtherulesvaryforeachstructure.

Phrasesandkeywords

Authorscanintermixmarkupwith textwhenthey needtoidentifypartofa paragraphoreven partofa sentenceashavingspecialsignificance.Phrasescanusuallycontainotherphrasesand keywordsaswellastext. Keywordscanonlycontaintext.

Images

Authorscaninsertimagesusingtheimageelement. Imagescanbe usedat theblocklevel,for exampletoshowscreencapturesordiagrams,orat thephraselevel,forexample toshowwhat iconsortoolbarbuttonslooklike.

Multimedia

Authorscancreatemultimediaforonline informationusingtheobjectelement,forexampleto displaySVGdiagramsthatcanberotatedand explored.

Topic modules

Therearethreebasic modulesintopic:fortables,formetadata, andforeverythingelse.

tblDecl.mod(DTD)

tblDeclMod.xsd,tblDeclGrp.xsd(Schema)

Definestheelementsforauthoringtables, basedontheCALStablemodelbutwith some DITA-specificextensions.

Chapter3.DITAmarkup 9

(15)

metaDecl.mod(DTD)

metaDeclMod.xsd,metaDeclGrp.xsd(Schema)

Definesmetadataelements.AlsousedbyDITAmaps,wheremetadatacanbedefinedfor multipletopicsat once.

topicAttr.mod,topicDefn.ent(DTDonly-foldedintootherschemafiles)) CommonDITAattributesand entities.

xml.xsd,ditaarch.xsd(Schemaonly-foldedintootherDTDfiles)

CommonXMLattributes andtheDITAarchitectureversion attribute topic.mod(DTD)

topicMod.xsd,topicGrp.xsd(Schema)

Definestherestoftheelementsinatopic.

Concepts

DITAconcept topicsanswer″Whatis...″questions.They includea body-levelelementwithabasic topic structure,includingsectionsandexamples.

Whyconcepts?

Conceptsprovidebackgroundthathelpsreadersunderstandessentialinformationabouta product, interface,ortask.Often,aconcept isanextended definitionofa majorabstractionsuchasaprocess or function.Conceptualinformationmayexplainaproductandhowit fitsintoitscategoryofproducts.

Conceptualinformationhelpsuserstomaptheirexistingknowledgetotasksandotheressential informationaboutaproductorsystem.

Conceptstructure

The<concept>elementisthetop-levelelementfora DITAconcept topic.Everyconcept containsa<title>

anda <conbody>andoptional <titlealts>,<shortdesc>,<prolog>,and<related-links>.

The<conbody>elementisthemainbody-level elementfora concept.Likethebodyelementofa general topic,<conbody>allowsparagraphs, lists,andotherelementsaswellassectionsand examples.But

<conbody>hasaconstraintthata sectionoranexamplecanbe followedonlybyothersectionsor examples.

Hereisanexampleofa simpleconcepttopic.

<title>Bird Calling</title>

<p>Bird calling attracts birds.</p>

<p>Bird calling requires learning:</p>

<ul>

<li>Popular and classical bird songs</li>

<li>How to whistle like a bird</li>

</ul>

</example>

</conbody>

</concept>

Modules

concept.mod (DTD)

conceptMod.xsd, conceptGrp.xsd(Schema)

(16)

Tasks

Tasktopicsanswer″Howdo I?″ questions,andhaveawell-definedstructure thatdescribeshowto completea proceduretoaccomplisha specificgoal.

Whytasks?

Tasksaretheessentialbuildingblocks forprovidingprocedureinformation.Atasktopicanswers the

″HowdoI?″questionbyprovidingprecisestep-by-step instructionsdetailingwhattodoand theorderin whichtodoit.Thetasktopicincludessectionsfordescribing thecontext,prerequisites, expectedresults, andotheraspectsofatask.

Taskstructure

The<task>elementisthetop-levelelementfora tasktopic.Everytasktopiccontainsa<title>anda

<taskbody>andoptional<titlealts>,<shortdesc>,<prolog>,and<related-links>.

The<taskbody>elementisthemainbody-levelelementinsideatasktopic.Ataskbodyhasavery specificstructure,with thefollowingelementsinthis order:<prereq>,<context>,<steps>,<result,

<example>and<postreq>. Eachofthebodysectionsisoptional.

<prereq>

Describesinformationneededbeforestartingthecurrenttask.

<context>

Providesbackgroundinformationforthetask.Thisinformationhelpstheuserunderstandwhat thepurposeofthetaskisandwhattheywillgainbycompletingthetask.Thissection shouldbe briefand doesnotreplace orrecreateaconcepttopiconthesamesubject,althoughthecontext sectionmayincludesomeconceptualinformation.

<steps>

Providesthemaincontent ofthetasktopic.Ataskconsistsofa seriesofstepsthataccomplish thetask.The<steps>sectionmust haveoneormore<step>elements,whichprovidethe specificsabouteachstep ininthetask.

The<step>elementrepresentsanactionthata usermust followtoaccomplisha task.Eachstep inataskmust containacommand<cmd>elementwhichdescribes theparticularaction theuser mustdotoaccomplishtheoveralltask.Thestepelementcanalsocontaininformation<info>, substeps<substeps>,tutorialinformation<tutorialinfo>,a stepexample<stepxmp>, choices

<choices>orastepresult<stepresult>,althoughthese areoptional.

<result>

Describestheexpectedoutcomeforthetaskasawhole.

<example>

Providesanexamplethatillustratesorsupportsthetask.

<postreq>

Describesstepsortasks thattheuser shoulddo afterthesuccessfulcompletionof thecurrent task.Itisoftensupportedbylinkstothenexttaskortasks inthe<related-links>section.

Here‘sanexampleofa tasktopic.

<title>Creating an ERTX file</title>

<context>Each morning before breakfast you need to create a fresh ERTX file.</context>

<steps>

<step><cmd>Start ERTX.</cmd></step></steps>

<step><cmd>Click New ERTX File.</cmd></step></steps>

(17)

</steps>

<result>You now have your ERTX file for today!</result>

</taskbody>

</task>

Modules

task.mod (DTD)

taskMod.xsd,taskGrp.xsd (Schema)

Reference

Referencetopics describeregularfeaturesof asubjectorproduct,suchascommandsinaprogramming language.

Whyreference?

Intechnicalinformation,referencetopics areoftenusedtocoversubjectssuchasthecommandsina programminglanguage.Referencetopics canholdanythingthathasregularcontent,suchasingredients forfoodrecipes,bibliographic lists,catalogues,and thelike.Referencetopicsprovidequickaccessto facts.Informationneededfordeeperunderstandingof areferencetopicorto performrelatedprocedures shouldbeprovidedina conceptortasktopic.

Referencestructure

The<reference>elementdefinesatop-levelcontainerforareference topic.Referencetopicshavethe samehigh-levelstructureastheothercoreDITAtopic types,witha title,shortdescription, andbody.

Withinthebody,referencetopicsorganize contentintooneormoresections, propertylists,ortables.

The<refbody>elementholdsthemaincontentofthereferencetopic.Referencetopics limitthebody structuretotables(bothsimpleandstandard),propertylists,syntax sections,andgenericsectionsand examples.

Alloftheelementsof<refbody>areoptionaland mayappearinanysequenceandnumber.

<section>

Representsanorganizationaldivisioninareference topic.Sectionsorganize subsetsof

informationwithina largertopic.Youcanonlyincludea simplelistofpeer sectionsina topic;

sectionscannotbenested.Asectionmayhaveanoptionaltitle.

<refsyn>

Containssyntaxorsignaturecontent (forexample,a command-lineutility’scallingsyntax,oran API’ssignature).The<refsyn>containsa brief,possiblydiagrammatic descriptionof thesubject’s interfaceorhigh-levelstructure.

<example>

Providescontainingexamples thatillustrateor supportthecurrenttopic.The<example> element hasthesamecontentmodelas<section>.

<table>

Organizesinformationaccordingintoa tabularrowsandcolumnsstructure. Tablemarkupalso allowsformorecomplexstructures, includingspanningrowsandcolumns,aswellastable captions.

<simpletable>

Holdsinformationinregularrowsandcolumnsand doesnotallowfora caption.

<properties>

Listspropertiesand theirtypes,values,anddescriptions.

Here‘sanexampleofa referencetopic.

(18)

<title>Bold property</title>

<shortdesc>(Read-write) Whether to use a bold font for the specified text string.</shortdesc>

<synph>

<var>object</var><delim>.</delim><kwd>Font</kwd><delim>.</delim>

<kwd>Bold</kwd><delim> = </delim><var>trueorfalse</var>

</synph>

</refsyn>

<propvalue>Boolean</propvalue>

</property>

<proptype>Legal values</proptype>

<propvalue>True (1) or False (0)</propvalue>

</property>

</properties>

</refbody>

</reference>

Modules

reference.mod(DTD)

referenceMod.xsd, referenceGrp.xsd(Schema)

Domains

ADITAdomaindefinesaset ofelementsassociatedwitha particularsubjectareaorauthoring requirementregardlessoftopictype.

Theelementsinadomainare definedina domainmodulewhichcanbeintegratedwith atopictypeto makethedomainelementsavailablewithin thetopictype structure.Currentlythefollowingdomains are provided:

Table1.DITAdomains

Domain Description Shortname Modulename

Typographic Forhighlightingwhentheappropriate semanticelementdoesn’texistyet

hi-d highlightDomain.mod (DTD) highlightDomain.xsd (Schema) Programming Fordescribingprogrammingand

programminglanguages

pr-d programmingDomain.mod (DTD) programmingDomain.xsd (Schema)

Software Fordescribingsoftware sw-d softwareDomain.mod (DTD)

softwareDomain.xsd (Schema) Userinterfaces Fordescribinguserinterfaces ui-d uiDomain.mod (DTD)

uiDomain.xsd (Schema) Utilities Forprovidingimagemapsandother

usefulstructures

ut-d utilitiesDomain.mod (DTD) utilitiesDomain.xsd (Schema)

DITA maps

Mapsorganizetopicsforoutputtoa specificdeliverable,includinggeneratingnavigationfilesandlinks torelatedtopics.

(19)

What are maps?

DITAmapsare documentsthatcollectandorganize referencestoDITAtopicstoindicatetherelationships amongthetopics. Theycanalsoserveasoutlinesortablesof contentsforDITAdeliverablesandasbuild manifestsforDITAprojects.

DITAmapsrepresentthearchitectureofaninformationset –whattopicsareneeded, inwhatorderor relationships,tosupporta particularsetofuser goalsorotherrequirements.

Mapsdescribethecontextinwhichthetopics willbe read– theaudience, platform,relationships,

requirementsof theinformationset.Inthisway, thetopicsthemselvesbecomerelatively context-free,and canbemoreeasilyusedandreused inmanydifferentcontexts, asdefinedbymaps.

Mapsdrawonarichsetofexistingbestpracticesandstandards fordefininginformationmodels, suchas hierarchicaltaskanalysis.They alsosupportthedefinitionofnon-hierarchicalrelationships,suchas matricesandgroups,whichprovidea setofcapabilitiesthathassomesimilaritiestoRDFand ISOtopic maps.

AmapfilereferencesoneormoreDITAtopicfilesusing<topicref>elements.The<topicref>elements canbenestedor otherwiseorganizedtoreflectthedesiredrelationshipsbetweenthereferencedtopics.

Mapfiles needtohaveafileextensionof.ditamap tobeprocessedproperly

Why DITA maps?

Mapsallowscalablereuseofcontentacrossmultiplecontexts. Theycanbeusedbyinformation architects,writers,andpublishers toplan,develop,and delivercontent.

Amongthespecificusesthatmapssupport:

Defininganinformationarchitecture

Themapcanbe usedtodefinewhattopics arerequiredforaparticularaudienceanduser goals, evenbefore thetopics themselvesexist.

Providinganauthoringinterface

Themapcanbe usedasa startingpoint forauthoringnew topicsandintegratingexistingones.

Definingwhattopicstobuild foraparticularoutput

Mapspointtotopicsthatareincludedinoutputprocessing.Authorsor publisherscanusemaps tospecifyasetof topicstotransformatthesametime,insteadoftransformingeachtopic individually.

Definingonlinenavigation

Mapscandefinetheonlinenavigationortableofcontentsforthetopicsitpoints to.

Definingwhattopicstoprint

Mapscandefineahierarchythatwilldeterminehowtopicswillbecombinedandnested for printing.

Definingrelated links

Mapsdefinerelationshipsamongthetopics theyreference;onoutput,these relationshipscanbe expressedasrelatedlinksamongthetopicsineachrelationship.

Common DITA map attributes and metadata

DITAmapshavemanyofthesamecommonattributesasDITAcontent,but alsohavesomeadditional onesforcontrolling theway relationshipsareinterpretedfordifferentoutputpurposes.

BecauseDITAmapsmayencodestructuresthatarewholly orpartiallyspecifictoa particularmediumor kindofoutput(forexample,hyperlinkedwebpages orprintedbooks),DITAmapscontainattributes to helpprocessorsinterpretthemapforeachkindof output.Theseattributesarenotavailablein DITA

(20)

content:individualtopics,onceseparatedfromthehigh-levelstructuresand dependenciesassociated witha particularkindofoutput,shouldbeentirelyreusableacrossmultiplemedia.

collection-type,linking

Thecontainmentstructureina mapcanbe usedtogeneraterelatedlinksorreferencesonoutput.The authorcanannotatethecontainmentstructuretoidentifya particularsetofsiblingsasbeingpartofa specifictype ofcollection,suchasa familyorsequence.Thecollection-typevaluefora groupofsiblings canindicatewhethertogeneratelinksamongthesiblings,andwhatkindoflinkstogenerate(for example,nextandprevious linksforasequence).Thecollection-typeattributecanalsoindicatehowthe parenttopicshouldlinktoitschildren(forexample,showingthechildlinksasa numberedlistwhenthe collection-typeissequence).

Bydefault,relationshipsbetweentopics inamaparereciprocal:childrenlinkto parentsandviceversa;

nextand previoustopicsina sequencelinktoeachother;topicsinneighboringtablecellslinktoeach other,and soon.Thisdefaultbehaviorcanbemodifiedusingthelinkingattribute,whichletsa topic modifyhowit participatesina relationship:

v Atopicreference withlinking=″none″doesnotexistinthemapforthepurposesof calculatinglinks v linking=″sourceonly″meansthatthetopicwilllinktoitsrelatedtopics butnotviceversa

v

linking=″targetonly″meansthattherelatedtopicswilllinktoit,but notviceversa

v linking=″normal″isthedefault,and meansthatlinkingwillbe reciprocal(thetopicwilllinktorelated topics,andtheywilllinkbacktoit)

</topicref>

</relrow>

</reltable>

A linkstoA1,A2,A3aschildren linkstoBasrelated

A1 linkstoAasaparent

linkstoA2asnextinthesequence A2 linkstoAasaparent

linkstoA1aspreviousinthesequence B linkstoAasrelated

Figure1.Simplelinkingexample

(21)

toc,navtitle, locktitle

Authorscanexclude entriesfromnavigationoutput(suchasan onlinetableofcontents, oraWebsite map)usingthetocattribute.By default,hierarchiesareincludedinnavigationoutput,and tablesare excluded.

Authorscanprovidea shorterversionofthetitleforuseinthenavigationusingthenavtitleattribute.By defaultthenavtitleattributeisignored, andusedonlytohelptheauthorkeeptrackofthetargettopic’s title.Thelocktitleattributecanbeset toensurethatthenavtitletakeseffectandoverridesanytitlevalues inthetargettopic,ordefinedelsewhere inthetopicreference metadata.

print,search

Youcanset attributesonatopictoindicatewhetheritshouldbe includedinprintedoutputand search indexes.

chunk,copy-to

Whena setoftopics istransformedusinga map,multi-topicfilescanbebroken intosmallerfiles,and multipleindividual topicscanbecombinedintoasingle largerfile,usingthechunkattribute.

Newtopicversionscanbe createdusingthecopy-toattribute.Thecopiedtopicwillhaveanew file name,andthemapcanoverridethedefaulttitleand shortdescbyprovidingvaluesfortheminthemap.

Sharedattributes

DITAmapsusethesamemetadataandreuseattributesthatDITAtopicsuse:

v product,platform,audience,otherprops,rev,status,importance,xml:lang,translate v id,conref

DITAmapsalso usemanyofthesameattributesthatareusedwithlinkorxrefelementsinDITAcontent:

</topicref>

</relrow>

</reltable>

A linkstoA1,A2aschildren

(nolinkstoBasachild,nolinkstoBasrelated) A1 linkstoAasaparent

linkstoA2asnextinthesequence (nolinkstoBasprevious)

A2 linkstoAasaparent

linkstoA1aspreviousinthesequence B linkstoAasrelated

Figure2.Linkingexamplewiththelinkingattribute

(22)

v format,scope,href, keyref,type,query

Sharedmetadataelements, andthelockmetaattribute

Youcanassociatetopicmetadatawitha topicorbranchoftopicsina map.By defaultmetadatainthe mapsupplements oroverridesmetadatainthetopic.Ifthelockmeta attributeisset to″no″,then the metadatain themapwillnottakeprecedence overthemetadatainthetopic,and conflictswillbe resolvedinfavorofthetopic.

Themetadataelementsinamaparethesameasthoseina topic,althoughtheymaybein aseparate order.Themapalsoincludesa shortdescriptionand alternatetitles,whichcanoverridetheirequivalents inthecontent.Insum, themapcanoverrideorsupplementeverythingaboutatopicexceptitscontent (inthetopic’sbodyelement).

DITA map structure

Mapsorganizetopicsinto hierarchies,tables,andgroups, andhavespecialelementsforreferencingother maps.

topicrefelementsarethebasicelementsofamap.AtopicrefcanpointtoaDITAtopic,map,ortoany otherresourcethatcanbe processedorlinkedto.

topicrefelementscanbe nestedtocreatea hierarchy,whichcanbe usedtodefineprintoutput,online navigation,and parent/childlinks.Thetopicheadelementcanbeusedfornodesinthehierarchythat providecontainerswithoutequivalenttopics:theyareequivalenttotopicrefelementswitha navtitlebut nohreforequivalentreferencingattribute.

Relationshiptablesaredefinedwiththereltableelement. Relationshiptablescanbe usedtodefine relationshipsamongthetopicsindifferentcellsofthesamerow.Ina relationshiptable,thecolumns definecommonattributes ormetadataforthetopics inthatcolumn.Therowsdefinerelationships,with eachcellrepresentinga differentroleintherelationship.Forexample,atablewith differentcolumnsfor concepts,tasks,andreference topicscouldbe usedtodefinetherelationshipbetweenataskand the topicsthatsupportit.

Bothhierarchiesandtablescanbeannotatedusingthecollection-typeattributetodefinesetsofsiblings thatarepartofa particularkindof collection,forexampleaset ofchoices,asequence,ora family.These collection-typescanaffectlinkgeneration,andmaybe interpreteddifferentlyfordifferentoutputs.

Groupsorcollectionsoutsideofa hierarchyortablecanbedefinedwiththetopicgroupelement, whichis equivalenttoatopicrefwithnoreferencingattributesortitles.Groupscanbe combinedwith hierarchies andtables,forexamplebyincludingagroupwithin atablecellorwithina setofsiblingsin ahierarchy.

Exampleofasimplerelationshiptable

</relheader>

</relcell>

</relcell>

(23)

</relcell>

</relrow>

</reltable>

type=″concept″ type=″task″ type=″reference″

A B C1

C2

A linkstoB,C1,C2 B linkstoA, C1,C2 C1,C2 linktoA,B

Inheritance of attributes and metadata

Someoftheattributesand metadataina mapcanbe inheritedbased onthestructuresinthemap.

Inheritanceisadditiveexceptwherethiswouldcausea conflict.Whenthereisaconflict, thevalue definedclosesttothetopicreftakeseffect.

Thefollowingattributesandmetadataelementsareinheritable:

Attributes

audience,platform,product,otherprops,rev linking,toc,print,search

chunk,format,scope,type Elements

author,source,publisher,copyright,critdates,permissions audience,category,keywords,prodinfo,othermeta

Attributesandmetadatacanbedefinedattherootlevel(attributesonthemapelementitself,topicmeta asadirectchildofthemapelement)toapplythemtotheentiremap. Theycanalsobeapplied atany pointinahierarchy,group,ortable.Tables canbeparticularlyusefulforattributeand metadata management,sincetheycanbeapplied toentirecolumnsorrowsaswellasindividualcells.

DITA map modules

Mapshavethesame modulestructureastopics,andshare someof thesame modulesfordefining metadata.

map.mod(DTD)

mapMod.xsd,mapGrp.xsd(Schema) Definesthebasemapstructures.

mapGroup.mod(DTD) mapGroup.xsd(Schema)

Addstopicgroupandtopicheadasspecializedvariantsoftopicref.

Common metadata elements

Thesamemetadataelementsareavailableinboth DITAtopictypesandDITAmaptypes. Thisallowsthe metadataassignedtoa topicwhenitiscreatedtobesupplemented oroverriddenwhenthetopicis includedina collection.

(24)

Publication metadata elements

Theseelementsprovidestandardinformationaboutthetopicasa publication.

Somecontentprovidersmight choosetoprovidesuchinformationonlyinthemaportheinitialtopicfor adeliverable.

author Thepersonororganizationwhocreatedthecontent.ThiselementisequivalenttotheDublin CoreCreator.

publisher

Theorganizationwho providesanddistributesthecontent.Thiselementisequivalenttothe DublinCorePublisher.

copyright

Thelegalownershipforthecontent.ThiselementisequivalenttotheDublinCoreRights.

Management metadata elements

Theseelementsprovidea basisfor managingthepublicationprocessfortopics.

Themanagementelementsmight getupdatedbyworkflowprocessesorprovideinputforsuchprocesses:

source Anidentifierornamefortheoriginalformofthecontent.ThiselementisequivalenttoDublin CoreSource.

critdates

Milestonesinthepublishing cycle.ThiselementisequivalenttoDublin CoreDate.

permissions

Specificationofthelevelofentitlementneededtoaccessforcontent.

resourceid

Theidentifierassociatedwiththetopicwhenprovidedtothespecifiedapplication.

Metadata qualification elements

Theseelementsqualifythetopicforprocessessuchasflagging,filtering,orretrieval.

Themetadataelementsapplytoanentiretopic,andcanalsobeusedina maptoapply metadatato multipletopicsat atime. Metadataelementscanexpandonthevaluesusedinmetadataattributes.(See metadataattributes.)For example,theaudienceelementinatopic’sprologcandefineanaudiencein termsoftype,job,and experiencelevel,andgiveit aname;whenthereiscontentwithinthetopic’sbody thatappliesonlytothataudience,thatcontentcanidentifyitsaudiencebythesamenameusedinthe prolog.

Whenmetadataisexpressedina map,it supplementsanymetadataexpressedinthetopics itreferences.

Whenmetadataina mapand atopicconflict(forexample,bothdefinea publisher),bydefaultthevalue inthemaptakesprecedence, ontheassumptionthattheauthor ofthemaphasmoreknowledgeofthe reusingcontextthantheauthorofthetopic.

audience

Thetype,job,experiencelevel, andothercharacteristicsofthereaderforthetopic.Manyofthese characteristicshaveenumeratedvalues,buttheenumerationcanbe extendedthroughassociated attributes.Forinstance,theaudiencetype enumerationcanbe extendedthroughan othertype attribute.Theaudienceelementcanelaboratevaluesusedbyaudienceattributes.

category

Aclassification ofthetopiccontent.Such classificationsarelikelytocomefroman enumeratedor hierarchicalset.ThiselementisequivalenttobothDublinCoreCoverageand DublinCore Subject.

(25)

keywords

Termsfroma controlledoruncontrolledsubjectvocabularythatapplytothetopic.

prodinfo

Thedefinitionoftheproductorplatformforthetopic.Theprodinfoelementcanelaboratevalues usedbytheproductandplatformattributes.

othermeta

Aname-value pairspecifyingothermetadataaboutthetopic.

Topic properties in topics and maps

Thepropertiesof atopiccanbespecified inthetopicitselforonreferencestothetopicwithinmaps.

Withinatopic,propertiescanbeexpressedusingmetadataattributesonthetopicelementorusing publication,management,ormetadataelementsinthetopicprolog.

Withinamap, thesamepropertiescanbe expressedonthetopicrefelementthatrefers tothetopic.That is,thetopicrefattributesandthetopicrefsubelementswithinthetopicmetacontainerapplytothe referencedtopic.Inaddition,themetadatapropertiesmapor topicrefelementsetthedefaultproperties fornestedtopicrefelementswithin themaphierarchy.Becausethetopicsina branchofthenavigation hierarchytypicallyhavecommonsubjectorproperties, thismechanismprovidesaconvenientway toset thepropertiesfora setoftopics.

Ifapropertyissetinboththemapandtopic,themappropertiesareadditiveif theproperty(suchasthe audiencetype) takesalistof values.If,instead,theproperty(suchastheimportance)takesa single value,themapproperty overridesthetopicproperty.

Exampleofaudiencemetadata inprologandbody

Thepracticeofprovidingfullmetadataintheprologandreferencingitfromattributeswhena subsetof metadataappliesisnotabestpractice.Prologmetadataandattributemetadatacanbeusedand

expressedindependently.Thecoordination shownhereispossiblebutisnotrequired.

<audience name="AdminNovice"

type="administrator"

job="customizing"

experiencelevel="novice">

</metadata>

</prolog>

....

<p audience="AdminNovice ProgrammerExp">This paragraph applies to both novice administrators and expert programmers</p>

Common attributes

ThefollowingattributesarecommonacrossmostDITAelements.

Identity attribute

TheDITAidentityattributeprovidesmechanismsforidentifying contentforretrievalorlinking.

Theidattributeassignsa uniqueidentifiertoanelementsotheelementcanbereferenced.Thescope of uniquenessfortheidattributedependsontherole oftheelementwithin theDITAarchitecture:

v Becausetopicsare thebasicunits ofinformationwithinDITA,theidattributefor thetopicmust be uniquewithinthedocumentinstance.

(26)

Atopicarchitectureassemblestopicsintoa deliverablebyreference.Toensurethattopicscanbe referenced,theidattributeisrequiredonthetopicelement.

ThecompleteidentifierforatopicconsistsofthecombinationoftheURIforthedocumentinstance,a separatinghashcharacter,and thetopicid(asin

http://some.org/some/directory/topicfile.xml#topicid).URIsaredescribedinRFC2396.Asis typicalwithURIs,a relativeURIcanbeusedastheidentifierforthedocumentinstancesolongasitis resolvableinthereferencingcontext.Forinstance,withina filesystemdirectory,thefilename ofthe documentinstancesuffices(asinsome/directory/topicfile.xml#topicid).Withinthesamedocument, thetopicidalonesuffices(asin #topicid).Wherethetopic elementistherootelementofthe

documentinstance,contextsoutside thedocumentinstancemayomitthetopicidwhenreferring tothe topicelement(asintopicfile.xml).

Thetopicidcanbe referencedbytopicrefs,links,xrefs,orconrefstothetopicaswell asindirectlyas partofreferencestothetopiccontent.

TheidattributeforDITAtopicsisoftypeIDinXML.

v Becausetopiccontentisalwayscontained withinatopic,theidattributefora topiccontentelement mustbe uniqueonlywithin thetopic.Thisapproachensuresmaintainable referencestocontent becausetheidentifierremainsvalidsolongasthedocumentinstance,topic,andcontentexist. The positionofthecontentwithinthetopicand thepositionofthetopicwithin thedocumentinstance can changewithoutinvalidatingthecontentidentifier.Inaddition,this approachavoidstheneed torewrite topiccontentidstoavoidnamingcollisionswhenaggregatingtopics.

Theidisoptionaland needbeaddedonlytomakethecontentreferenceable.

Thecompleteidentifierfortopiccontentconsistsofthecombinationof thecompleteidentifierforthe topic,aseparatingsolidus(/),and thetopiccontent id(asin

http://some.org/some/directory/topicfile.xml#topicid/contentid).Asnotedbefore,thetopic identifierportioncanusearelativeURIforthedocumentinstanceincontextswheretherelativeURI canberesolved (asinsome/directory/topicfile.xml#topicid/contentid).

Thecontainingtopicidmustalways beincludedwhenreferencinganelementid.Otherwise,a referencetoanothertopiccouldn’tbe distinguishedfromareferencetoan elementwithin thesame topic.Forreferenceswithinthesamedocumentinstance,theidentifierforthedocumentinstancecan beomittedaltogether(asin#topicid/contentid).

Theidattributeforelementswithin DITAtopics isnotoftype IDand isnotrequiredtobeunique.

v Fora map,theidof amap,topicref,oranchormustbe uniquewithin thedocumentinstance.This approachensuresthatthese elementscanbe referencedoutsidethemapwithoutqualification bythe mapid.

Fortheanchorelement,whichexistsonlytoidentifya positionwithina mapasa targetforreferences, theidattributeisrequired.Fortheotherelements,theidattributeisoptional.

Aswitha topic,thecompleteidentifierconsistsofthecombinationoftheabsoluteURIforthemap documentinstanceand theelementid(asin

http://some.org/some/directory/mapfile.xml#topicrefid).

Theidattributeformaps,topicrefs,andanchorsisoftype ID.

v Theidfor arelationshiptableelementmustbe uniqueonlywithin themap.

Aswithtopiccontent,thefullidentifierconsistsofthecombinationof theabsoluteURIforthemap andtheidfortherelationshiptable element(asin

http://some.org/some/directory/mapfile.xml#mapid/reltableid).

Theidattributeforreltable elementsisnotoftype IDand isnotrequiredto beunique.

Content reference attribute

TheDITAconref attributeprovides amechanismforreuseof contentfragments.The conrefattribute storesa referencetoanotherelementandisprocessedtoreplace thereferencingelementwiththe referencedelement.

(27)

Theelementcontaining thecontentreferenceactsasa placeholderforthereferencedelement.The

identifierforthereferencedelementmustbe eitherabsoluteor resolvableinthecontextofthereferencing element.(See“Identityattribute” onpage20forthedetailsonidentifiers.)

Moreformally,theDITAconrefattributecanbeconsideredatransclusionmechanism.Inthatrespect, conrefissimilartoXIncludeaswellasHyTimevaluereferences. DITAdiffersfromthesemechanisms, however,bycomparingtheconstraintsofeachcontexttoensuretheongoingvalidityofthereplacement contentinitsnewcontext.Inotherwords,conrefvalidity doesnotapplysimplytothecurrentcontentat thetimeofreplacement,but totherangesofpossiblecontent giventheconstraints ofthetwodocument types.Avalidconref processordoesnotallowtheresolutionofa reuserelationshipthatcouldbe renderedinvalidundertherulesofeitherthereusedorreusingcontent.

Ifthereferencedelementisthesametype asthereferencingelementand thelistofdomains inthe referencedtopicinstance (declaredonthedomainsattribute)isthesameasorasubsetofthelistof domainsinthereferencingdocument,theelementsetallowedinthereferencedelementisguaranteedto bethesameas,orasubsetof,theelementsetallowedintheplaceholderelement.Inthepreferred approach,aprocessor resolvingaconref shouldtoleratespecializationsofvalidelementsandgeneralize elementsinthecontentfragmentasneededforthereferencingcontext.

Replacementoftheplaceholder occursafter parsingofthedocumentbutpriortoanystylingorother transformationalorpresentationaloperationsonthefulltopic.

Thetargetoftheconrefmaybe substitutedbased onbuild-timeorruntimeconditions. Forexample, contentsuchasproductnamesorinstallpaths canbeseparatedoutfromtopiccontentsincetheychange whenthetopicisreused byotherproducts;thereusingproductcansubstitute theirowntargetsforthe conreftoallowresolutiontotheirownproductnameand installpaths,and soon.

Thetargetofa conrefmust beina validDITAtopicorDITAmap. FragmentsofDITAcontentdonot containenoughinformationontheirowntoallowtheconrefprocessortodeterminethevalidityofa referencetothem.

Metadata attributes

Themetadataattributesexpressqualificationsonthecontent.Thesequalificationscanbeusedtomodify theprocessingofthecontent.

Onetypicaluseofthemetadataattributesistofiltercontentbased ontheirvalues.Anothertypicaluseis toflagcontentbased ontheirvalues,forexamplebyhighlightingtheaffectedtextonoutput.Typically audience,platform,product,and otherpropsare usedforfiltering,and thesame attributesplusrev are usedfor flagging.Status andimportanceare usedfortool-specificor transform-specificbehavior,for examplemarkingstepsinataskasoptionalorrequired.

Ingeneral,a metadataattributeprovides alistofoneormore qualificationvalues,separatingthose valueswithwhitespace. Forinstance,an audienceattributeofadministrator programmerqualifiesthe contentasapplyingtoadministrators andprogrammers.

Fora topic,theaudience, platform,and productmetadatacanbeexpressedwithattributesonthetopic elementor withelementswithinthetopicprolog. Whilethemetadataelementsaremoreexpressive,the meaningofthevaluesisthesame,andcanbeusedincoordination:forexample,theprologelementscan fullydefinetheaudiencesfora topic,and thenmetadataattributescanbeusedwithin thecontentto identifypartsthatapplytoonlysomeofthoseaudiences.

audience

Thevaluesfromtheenumeratedattributesoftheaudiencemetadataelementhavethesame meaningwhenusedintheaudienceattributeofacontentelement. Forinstance,the″user″value hasthesamemeaningwhetherappearing inthetype attributeoftheaudienceelementforatopic

(28)

orintheaudienceattributeofa contentelement.Theprinciple appliestothetype,job,and experiencelevelattributesoftheaudienceelement.

Thevaluesintheaudienceattributemayalsobe usedtoreference amorecompletedescriptionof anaudienceinanaudienceelement. Usethenameoftheaudienceintheaudienceelementwhen referringtothesameaudiencein anaudienceattribute.

Theaudienceattributetakesa blank-delimitedlistofvalues,whichmayormaynotmatchthe namevalue ofanyaudienceelements.

platform

Theplatformmightbe theoperatingsystem,hardware,orotherenvironment.Thisattributeis equivalenttotheplatformelementforthetopicmetadata.

Theplatformattributetakesablank-delimitedlistofvalues,whichmayormaynotmatchthe contentofaplatformelementintheprolog.

product

Theproductorcomponentname,version,brand,orinternalcodeornumber.Thisattributeis equivalenttotheprodinfo elementforthetopicmetadata.

Theproductattributetakesa blank-delimitedlistof values,whichmayormaynotmatchthe valueoftheprodnameelementintheprolog.

importance

Thedegreeofpriorityofthecontent.Thisattributetakesasinglevalue fromanenumeration.

rev Theidentifierfortherevision level.

status Thecurrentstateof thecontent.Thisattributetakesasinglevalue fromanenumeration.

otherprops

Acatchallformetadataqualificationvaluesaboutthecontent.Thisattributeisequivalenttothe othermetaelementforthetopicmetadata.

Theproductattributetakesa blank-delimitedlistof values,whichmayormaynotmatchthe valuesof othermetaelementsintheprolog.

Theattributecanalso takelabelledgroupsofvalues.Alabelled groupconsistsof astringvalue followedbyanopenparenthesisfollowedbyoneor moreblank-delimitedvaluesfollowedbya closeparenthesis.Thesimpleformatissufficientwhenaninformationsetrequiresonlyone additionalmetadataaxis,inadditiontothebasemetadataattributesofproduct, platform,and audience.Thefullformatisusefulwhenaninformationset requirestwoormoreadditional metadataaxes.Aprocesscandetectwhichformatisinusebythepresenceofparenthesesinthe attribute.

For example,a simple otherprops value list:<codeblockotherprops="javacpp">

For example,a complex otherpropsvalue list: <codeblockotherprops="proglang(java cpp) commentformat(javadoc html)">

Miscellaneous Attributes

Thexml:langattributeidentifiesthelanguageofatopicorcontentfragment. Theoutputclassattachesa classifyinglabeltoanelement.

MiscellaneousattributesofDITAelementsincludethefollowing xml:lang

Thexml:langattribute’sbehaviorisdescribedindetail intheXMLspecification:

http://www.w3.org/TR/REC-xml/#sec-lang-tagTheattributeidentifies alanguagebymeansof thestandardlanguageandcountrycodes (asdescribedinRFC3066).Forinstance,French

(29)

Canadianwouldbeidentifiedbythevaluefr-ca.Asisusual,thelanguageappliestothe containedcontentandattributes ofthecurrentelementandcontained elements,otherthan fragmentsthatdeclarea differentlanguage.

outputclass

Theoutputclassattributeprovidesalabelononeormoreelementinstances,typicallytospecifya roleorothersemanticdistinction.Astheoutputclassattributedoesn’tprovideaformaltype declarationorthestructuralconsistencyof specialization,itshouldbeusedsparingly,oftenonly asa temporarymeasurewhilea specializationisdeveloped.Forexample,<uicontrol>elements thatdefinebuttonlabelscouldbe distinguishedbyaddingan outputclass:<uicontrol

outputclass="button">Cancel</uicontrol>.Theoutputclassvalue couldbe usedtotriggerXSLT orCSSrules,aswell asproviding amappingtobe usedforfuturemigrationtoa more

specializedset ofUIelements.

Architectural attributes

DITAprovides someattributes toprovidetypeinformationtoprocessorsinsteadofqualificationsor propertiesof content.

Ordinarily,architecturalattributesdon’tappearinthesourcefilesfordocumentinstances. Instead, architecturalattributesappearindocumentinstancesthroughdefaults setintheDTDorSchema declaration.Thispracticeensures thatthecreationofdocumentinstancescannotproduceinvalidvalues forthearchitecturalattributes.Theseattributesare asfollows:

class Thisattributeidentifies thespecializationmodulefortheelementtypeaswellastheancestor elementtypesandthespecializationmodulestowhichtheybelong.EveryDITAelementhasa classattribute.

domains

Thisattributeidentifies thedomainspecializationmodules usedina topicand,foreachdomains module,itsmoduledependencies. Everytopicandmapelementhasadomains attribute.

DITAArchVersion

Thisattributeidentifies theversionof theDITAarchitectureusedbytheDTDorschema.Every topicandmapelementhasaDITAArchVersionattribute.Theattributeisdeclaredina DITA namespacetoallownamespace-sensitivetoolstodetectDITAmarkup.

TomakethedocumentinstanceusablewithouttheDTDorSchemadeclaration,a normalizationprocess caninstillthearchitecturalattributesinthedocumentinstance.

Conditional processing

Conditionalprocessingisthefilteringorflaggingofinformationbasedonprocessing-timecriteria DITAtriestoimplementconditionalprocessinginasemantically meaningfulway:ratherthanallowing arbitraryvaluestoaccumulateina documentovertimeinageneral-purposeprocessingattribute,with meaningonlytotheoriginalauthor,weencouragetheauthoringofmetadatausingspecificmetadata attributesoncontent.Thesemetadatavaluescanthenbe leveragedbyanynumberofprocesses, includingfiltering,flagging,search,and indexing,ratherthanbeingsuitableforfilteringonly.

Therearefourattributesintendedfor conditionalprocessing, availableonmostelements:

v product:theproductthatisthesubjectofthediscussion.

v platform:theplatformonwhichtheproductisdeployed.

v audience:theintendedaudienceofthetext

v rev:therevisionordraftnumber ofthecurrentdocument(typicallyusedforflaggingonly,notfor filtering)

v otherprops:anythingelse

OASIS Darwin Information Typing Architecture (DITA) Architectural Specification v1.0