(cid:1)(cid:2)(cid:3) DITA Specification draft ii DITASpecificationdraft Contents Chapter 1. About the DITA Specification 1 || Dataextensibility . . . . . . . . . . . 25 Commonattributes. . . . . . . . . . . . 26 Chapter 2. An introduction to DITA . . . 3 Identityattribute . . . . . . . . . . . 26 Contentreferenceattribute . . . . . . . . 27 Definitionsandbackgroundconcepts . . . . . . 3 || Metadataattributes. . . . . . . . . . . 28 Terminology . . . . . . . . . . . . . 4 || MiscellaneousAttributes . . . . . . . . . 29 Namingconventionsandfileextensions . . . . . 5 Architecturalattributes . . . . . . . . . 30 || Conditionalprocessing . . . . . . . . . 30 Chapter 3. DITA markup . . . . . . . . 7 DITAtopics. . . . . . . . . . . . . . . 7 Chapter 4. DITA specialization. . . . . 35 Whataretopics? . . . . . . . . . . . . 7 || Whatisspecialization? . . . . . . . . . . 35 Whytopics? . . . . . . . . . . . . . 7 || Whyspecialization? . . . . . . . . . . . 36 Informationtyping . . . . . . . . . . . 8 || Structuralversusdomainspecialization . . . . . 36 Topicstructure. . . . . . . . . . . . . 8 || Limitsofspecialization . . . . . . . . . . 37 Topiccontent . . . . . . . . . . . . . 9 || Specializefromgenericelements . . . . . . 37 Topicmodules. . . . . . . . . . . . . 9 || Customizedsubsetdocumenttypesforauthoring 38 Concepts . . . . . . . . . . . . . . 10 | MapfromcustomizeddocumenttypetoDITA Tasks . . . . . . . . . . . . . . . 11 || duringpreprocessing . . . . . . . . . . 38 Reference . . . . . . . . . . . . . . 12 Specializationincontent . . . . . . . . . . 39 Domains . . . . . . . . . . . . . . 13 Whyspecializationincontent? . . . . . . . 39 DITAmaps . . . . . . . . . . . . . . 13 || Specializationofattributes . . . . . . . . 39 Whataremaps?. . . . . . . . . . . . 14 Theclassattribute . . . . . . . . . . . 39 WhyDITAmaps? . . . . . . . . . . . 14 Classattributesyntax . . . . . . . . . . 40 || CommonDITAmapattributesandmetadata . . 14 Thedomainsattribute. . . . . . . . . . 41 DITAmapstructure . . . . . . . . . . 17 || Specializationvalidity. . . . . . . . . . 41 || Inheritanceofattributesandmetadata . . . . 18 Generalization . . . . . . . . . . . . 42 DITAmapmodules. . . . . . . . . . . 18 Specializationindesign . . . . . . . . . . 44 || Howandwhentousebookmap . . . . . . 19 Whyspecializationindesign? . . . . . . . 44 || Transitionaltext . . . . . . . . . . . . 21 Modularizationandintegrationofdesign . . . 44 || ThexNALdomain . . . . . . . . . . . 22 Specializationinprocessing . . . . . . . . . 50 || Commonmetadataanddataelements . . . . . 23 Usingtheclassattribute . . . . . . . . . 50 || Publicationmetadataelements . . . . . . . 23 || Processingspecializedattributes . . . . . . 51 || Managementmetadataelements . . . . . . 23 Modularizationandintegrationofprocessing . . 51 || Metadataqualificationelements . . . . . . 23 || Topicpropertiesintopicsandmaps . . . . . 24 iii iv DITASpecificationdraft Chapter 1. About the DITA Specification The Darwin Information TypingArchitecture (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: v The DTDs and schemas that define DITAmarkup for the base DITAdocument types, as well as catalog files. While the DTDs and schemas should define the same DITAelements, the DTDs are normative if there is ever any discrepancy. v The language reference that provides explanations for each element in the base DITAdocument types v This document, which comes in three parts: – an introduction, which provides background concepts and an overview of the architecture – the DITAmarkup specification, which provides an overview of DITA’s base document types – the DITAspecialization specification, which provides details of the mechanisms DITAprovides for defining and extending DITAdocument types. This document is part of the technical specification for the DITAarchitecture. While the specification does contain some introductory information, it is not intended as an introduction to DITAnor as a users guide. The intended audience of this specification consists of implementers of the DITAstandard, including tool developers and specializers. Editors Michael Priestley and JoAnn Hackos Members PaulAntonov France Baril Robin Cover, OASIS Don Day, IBM Stanley Doherty, Sun Microsystems Bruce Esrig, Lucent Technologies Yas Etessam, Blast Radius Rob Frankland, Rascal Software Paul Grosso,Arbortext JoAnn Hackos Eric Hixson, BMC Software Eliot Kimber, Innodata Isogen Chris Kravogel Deborah Lapeyre Seraphim Larsen, Intel Indi Liepa, Nokia Kirsten Nothstine, BMC Software Paul Prescod, Blast Radius Michael Priestley, IBM David Schell, IBM 1 Kevin Shaum, BMC Software Wendy Shepperd, BMC Software Jerry Smith, US Department of Defense Dana Spradley, Oracle Sharon Veach, Sun Microsystems Mike Wethington, BMC Software Christopher Wong, Idiom Technologies Additional contributors Patricia Best, Sun Microsystems David Brainard, BMC Software Jarno Elovirta, Nokia Nancy Harrison, IBM Erik Hennum, IBM Alan Houser John Hunt, IBM Helena Jerney,Actional Corporation Shawn Jordan Tyde Richards Bruce Sesnovich, Sun Microsystems Eric Sirois, IBM Zachary Taylor, BMC Software Scott Tsao, Boeing 2 DITASpecificationdraft Chapter 2. An introduction to DITA DITAis an architecture for creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways. It is also an architecture for creating new topic types and describing new information domains based on existing types and domains. The process for creating new topic types and domains is called specialization. Specialization allows the creation of very specific, targeted document type definitions while still sharing common output transforms and design rules developed for more general types and domains, in much the same way that classes in an object-oriented system can inherit methods of ancestor classes. DITAtopics are XMLconforming.As such, they are readily viewed, edited, and validated with standard XMLtools, although some features such as content referencing and specialization may benefit from customized support. Definitions and background concepts The following terms have specific meanings in DITAwhich should be understood before reading either the DITAmarkup specification or the DITAspecialization specification. Basic concepts The following are basic concepts used in DITA. “What are topics?” on page 7 Atopic is a unit of information with a title and content, short enough to be specific to a single subject or answer a single question, but long enough to make sense on its own and be authored as a unit. “What are maps?” on page 14 DITAmaps are documents that collect and organize references to DITAtopics to indicate the relationships among the topics. They can also serve as outlines or tables of contents for DITA deliverables and as build manifests for DITAprojects. “What is specialization?” on page 35 Specialization allows you to define new kinds of information (new structural types or new domains of information), while reusing as much of existing design and code as possible, and minimizing or eliminating the costs of interchange, migration, and maintenance. “Structural versus domain specialization” on page 36 Structural specialization defines new types of structured information, such as new topic types or new map types. Domain specialization creates new markup that can be useful in multiple structural types, such as new kinds of keywords, tables, or lists, or new conditional processing attributes. “Integration” on page 45 Each domain specialization or structural specialization has its own design module. These modules can be combined to create many different document types. The process of creating a new document type from a specific combination of modules is called integration. “Customization” on page 51 When you just need a difference in output, you can use DITAcustomization to override the default output without affecting portability or interchange, and without involving specialization. “Generalization” on page 42 Specialized content can be generalized to any ancestor type. The generalization process can preserve information about the former level of specialization to allow round-tripping between specialized and unspecialized forms of the same content. 3 Terminology DITAuses a number of terms in particular or unique ways. Within the scope of this specification, the following terms are used when talking about DITAmodels, DITAdeclarations, and DITAinstances. Model terminology DITAcan be understood at the level of an abstract model without reference to particular DTDs, schemas, or actual XMLdocuments. When discussing DITAconcepts at this level, the following terminology is used. Element type Defines the structure and semantics for a fragment of content. Specialized element type Defines an element type as a semantic refinement of another element type. The content allowed by the specialized element type must be a subset of or identical to the content allowed by the original element type. Topic type An element type that defines a complete unit of content. The topic type provides the root element for the topic and, through contained element types, substructure for the topic instances. The root element of the topic type is not necessarily the same as the root element of a document type: document types may nest multiple topic types, and may also declare non-DITAwrapper elements as the root element for compatibility with other processes. Map type An element type that defines a set of relationships for topic instances. The map type provides the root element and, through contained element types, substructure for the map instances. The map substructure provides hierarchy, group, and matrix organization of references to topic instances. Structural type Atopic type or map type. Domain Aset of elements that support a specific subject area. Elements in a domain can be integrated with topic or map types to enhance their semantic support for particular kinds of content. For example, the structural type <topic> declares the <keyword> element; when integrated with a domain for describing user interfaces, new keyword specializations (such as <wintitle>) become available wherever <keyword> was allowed in the original structural type. Document type The full set of element types defined in the modules that are integrated by the document type shell.ADITAdocument type may support authoring multiple topic types or multiple map types, but not a mix of the two. The structural types can be augmented with elements from domains. The term ″doc um ent type ″ is used for co mpat ibilit y w ith existing stan dards, sin ce thi s is the po int at which DITA’s set of topic, domain, and map types are assembled into a document type that is functionally equivalent to a traditional non-modularized document type. Declaration terminology When the model is expressed in a DTD or schema, the various element types are declared. When referring to these declarations, the following terminology is used. Element declaration The representation within a schema technology (such as DTD, XMLSchema, or Relax NG) for an element type. Type module The representation within a schema technology for the element types uniquely defined by a topic type, map type, or domain. 4 DITASpecificationdraft Topic module The representation within a schema technology for the element types uniquely defined by a topic type. Map module The representation within a schema technology for the element types uniquely defined by a map type. Structural module Atopic or map module. Domain module The representation within a schema technology for the element types uniquely defined by a domain. Document type shell The representation within a schema technology for a shell that declares no element types itself but points to and assembles topic, map, and domain modules. Document type declaration The representation within a schema technology for a document type. The document type declaration includes the declaration modules assembled by the document declaration shell. Instance terminology When actual documents, topics, and elements are created based on a DITAdocument type, the following terminology is used. Element instance An occurrence of an element type in a document. Topic instance An occurrence of a topic type in a document. Map instance An occurrence of a map type in a document. Structural type instance An occurrence of a topic type or a map type in a document. Document instance Adocument whose meaning and validity are determined by a document type declaration. Naming conventions and file extensions The following naming conventions and file extensions are in use by DITA. DITA topic instance files *.xml, *.dita DITA map instance files *.ditamap DTD structural module files typename.mod DTD domain module files typenameDomain.mod typenameDomain.ent Schema structural module files typenameMod.xsd typenameGrp.xsd Chapter2.AnintroductiontoDITA 5 Schema domain module files typenameDomain.xsd CSS override files typename.css customization-purpose.css XSLT override files typename.xsl customization-purpose.xsl 6 DITASpecificationdraft