DITA-dsf.xml@ 99012

Last change on this file since 99012 was 98584, checked in by vboxsync, 2 years ago
Docs: bugref:10302. Setting svn properties of DITA-OT library.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 49.8 KB

Line
1	<?xml version='1.0' encoding='utf-8'?>
2	<!-- This file is part of the DITA Open Toolkit project hosted on
3	Sourceforge.net. See the accompanying license.txt file for
4	applicable licenses.-->
5	<!-- (c) Copyright IBM Corp. 2004, 2005 All Rights Reserved. -->
6
7	<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
8
9	<topic id="specarch" xml:lang="en-us">
10	<title>Specializing topic types in DITA</title>
11	<shortdesc>The Darwin Information Typing Architecture (DITA) provides a way for documentation authors and architects to create collections of typed topics that can be easily assembled into various delivery contexts. Topic specialization is the process by which authors and architects can define topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type.</shortdesc>
12	<prolog>
13	<author>Michael Priestley; IBM Corporation; Toronto, Canada; [email protected]; Michael Priestley is an information developer for the IBM Toronto Software Development Laboratory. He has written numerous papers on subjects such as hypertext navigation, singlesourcing, and interfaces to dynamic documents. He is currently working on XML and XSL for help and documentation management.</author>
14	<critdates>
15	<created date="23 February 2001"/>
16	</critdates>
17	<metadata>
18	<audience type="user" job="other" experiencelevel="general"/>
19	<category>General</category>
20	<keywords>
21	<keyword>DITA</keyword>
22	<keyword>XML</keyword>
23	<keyword>topic</keyword>
24	<keyword>information architecture</keyword>
25	<keyword>architectural forms</keyword>
26	<keyword>specialization</keyword>
27	<keyword>information type</keyword>
28	<keyword>document type</keyword>
29	<keyword>DTD</keyword>
30	<keyword>document metadata</keyword>
31	<keyword>documentation</keyword>
32	<keyword>technical writing</keyword>
33	<keyword>user assistance</keyword>
34	<keyword>helps</keyword>
35	</keywords>
36	</metadata>
37	</prolog>
38	<body>
39	<p>The point of the XML-based Darwin Information Typing Architecture (DITA) is to create modular technical documents that are easy to reuse with varied display and delivery mechanisms, such as helpsets, manuals, hierarchical summaries for small-screen devices, and so on. This article explains how to put the DITA principles into practice with regards to the creation of a DTD and transforms that will support your particular information types, rather than just using the base DITA set of concept, task, and reference. </p>
40	<p>Topic specialization is the process by which authors and architects define new topic types, while maintaining compatibility with existing style sheets, transforms, and processes. The new topic types are defined as an extension, or delta, relative to an existing topic type, thereby reducing the work necessary to define and maintain the new type. </p>
41	<p>The examples used in this paper use XML DTD syntax and XSLT; if you need background on these subjects, see Resources. </p>
42	</body>
43	<topic id="archcontext">
44	<title>Architectural context </title>
45	<body>
46	<p>In SGML, architectural forms are a classic way to provide mappings from one document type to another. Specialization is an architectural-forms-like solution to a more constrained problem: providing mappings from a more specific topic type to a more general topic type. Because the specific topic type is developed with the general topic type in mind, specialization can ignore many of the thornier problems that architectural forms address. This constrained domain makes specialization processes relatively easy to implement and maintain. Specialization also provides support for multi-level or hierarchical specializations, which allow more general topic types to serve as the common denominator for different specialized types. </p>
47	<p>The specialization process was created to work with DITA, although its principles and processes apply to other domains as well. This will make more sense if you consider an example: Given specialization and a generic DTD such as HTML, you can create a new document type (call it MyHTML). In MyHTML you could enforce site standards for your company, including specific rules about forms layout, heading levels, and use of font and blink tags. In addition, you could provide more specific structures for product and ordering information, to enable search engines and other applications to use the data more effectively. </p>
48	<p>Specialization lets MyHTML be defined as an extension of the HTML DTD, declaring new element types only as necessary and referencing HTML's DTD for shared elements. Wherever MyHTML declares a new element, it includes a mapping back to an existing HTML element. This mapping allows the creation of style sheets and transforms for HTML that operate equally well on MyHTML documents. When you want to handle a structure differently (for example, to format product information in a particular way), you can define a new style sheet or transform that holds the extending behavior, and then import the standard style sheet or transform to handle the rest. In other words, new behavior is added as extensions to the original style sheet, in the same way that new constraints were added as extensions to the original DTD or schema. </p>
49	</body>
50	</topic>
51	<topic id="specinfotypes">
52	<title>Specializing information types</title>
53	<body>
54	<p>The Darwin Information Typing Architecture is less about document types than information types. A document is considered to be made up of a number of topics, each with its own information type. A topic is, simply, a chunk of information consisting of a heading and some text, optionally divided into sections. The information type describes the content of the topic: for example, the type of a given topic might be "concept" or "task." </p>
55	<p>DITA has three types of topic: a generic topic, or information-typed concept, task, and reference topics. Concept, task, and reference topics can all be considered specializations of topic: </p>
56	<image href="image/basediag.gif" alt="Base information types" height="74" width="300"/>
57	<p>Additional information types can be added to the architecture as specializations of any of these three basic types, or as a peer specialization directly off of topic; and any of these additional specializations can in turn be specialized: </p>
58	<image href="image/manydiag.gif" alt="Specialized information types" height="253" width="494"/>
59	<p>Each new information type is defined as an extension of an existing information type: the specializing type inherits, without duplication, any common structures; and the specializing type provides a mapping between its new elements and the general type's existing elements. Each information type is defined in its own DTD module, which defines only the new elements for that type. A document that consists of exactly one information type (for example, a task document in a help web) has a document type defined by all the modules in the information type's specialization hierarchy (for example, task.mod and topic.mod). A document type with multiple information types (for example, a book consisting of concepts, tasks, and reference topics) includes the modules for each of the information types used, as well as the modules for their ancestors (concept.mod, task.mod, reference.mod, plus their ancestor topic.mod). </p>
60	<p>Because of the separation of information types into modules, you can define new information types without affecting ancestor types. This separation gives you the following benefits: <ul>
61	<li>Reduces maintenance costs: each authoring group maintains only the elements that it uniquely requires</li>
62	<li>Increases compatibility: the core information types can be centrally maintained, and changes to the core types are reflected in all specializing types</li>
63	<li>Distributes control: reusability is controlled by the reuser, instead of by the author; adding a new type does not affect the maintenance of the core type, and does not affect other users of different types</li>
64	</ul> Any information-typed topic belongs to multiple types. For example, an API description is, in more general terms, a reference topic.</p>
65	</body>
66	</topic>
67	<topic id="refxmp">
68	<title>Specialization example: Reference topic</title>
69	<body>
70	<p>Consider the specialization hierarchy for a reference topic:</p>
71	<image href="image/reftopicdiag.gif" alt="Reference topic specialization hierarchy" height="89" width="230"/>
72	<section>
73	<p>Table 1 expresses the relationship between the general elements in topic and the specific elements in reference. Within the table, the columns, rows, and cells indicate information types, element mappings, and elements. Table 2 explains the relationships in detail to help you interpret Table 1. </p>
74	<table frame="all">
75	<title>Relationships between topic and a specialization based on it </title>
76	<tgroup cols="2">
77	<colspec colnum="1" colname="col01" colwidth="*"/>
78	<colspec colnum="2" colname="col1" colwidth="*"/>
79	<thead>
80	<row>
81	<entry colname="col01"> Topic </entry>
82	<entry colname="col1"> Reference</entry>
83	</row>
84	</thead>
85	<tbody>
86	<row>
87	<entry>(topic.mod) </entry>
88	<entry> (reference.mod)</entry>
89	</row>
90	<row>
91	<entry> topic </entry>
92	<entry> reference </entry>
93	</row>
94	<row>
95	<entry> title </entry>
96	<entry/>
97	</row>
98	<row>
99	<entry colname="col01"> body </entry>
100	<entry colname="col1"> refbody </entry>
101	</row>
102	<row>
103	<entry colname="col01" morerows="1">simpletable</entry>
104	<entry colname="col1">properties</entry>
105	</row>
106	<row>
107	<entry colname="col1"/>
108	</row>
109	<row>
110	<entry morerows="1"> section </entry>
111	<entry> refsyn</entry>
112	</row>
113	<row>
114	<entry colname="col1"/>
115	</row>
116	</tbody>
117	</tgroup>
118	</table>
119	<dl spectitle="How to interpret Table 1.">
120	<dlhead>
121	<dthd>Structure</dthd>
122	<ddhd>Associations</ddhd>
123	</dlhead>
124	<dlentry>
125	<dt>Columns</dt>
126	<dd>The <b>Topic</b> column shows basic <filepath>topic</filepath> structure, which comprises a title and body with optional sections, as declared in a DTD module called <userinput>topic.mod</userinput> . The <b>Reference</b> column shows a more specialized structure, with <filepath>reference</filepath> replacing <filepath>topic</filepath>, <filepath>refbody</filepath> replacing <filepath>body</filepath>, and <filepath>refsyn</filepath> replacing <filepath>section</filepath>; these new elements are declared in a DTD module called <userinput>reference.mod</userinput> .</dd>
127	</dlentry>
128	<dlentry>
129	<dt>Rows</dt>
130	<dd>Each row represents a mapping between the elements in that row. The elements in the <b>Reference</b> column specialize the elements in the <b>Topic</b> column. Each general element also serves as a category for more specialized elements in the same row. For example, <filepath>reference</filepath>'s <filepath>refsyn</filepath> is a kind of <filepath>section</filepath>.</dd>
131	</dlentry>
132	<dlentry>
133	<dt>Cells</dt>
134	<dd>Each cell in a column represents the following possibilities in relation to the cell to its left: <ul>
135	<li>A blank cell: The element in the cell to the left is reused as-is. For example, a <filepath>reference</filepath><filepath>title</filepath> is the same as a <filepath>topic</filepath><filepath>title</filepath>, and <filepath>topic</filepath>'s declaration of the <filepath>title</filepath> element can be used by <filepath>reference</filepath>.</li>
136	<li>A full cell: An element that is specific to the current type replaces the more general element to the left. For example, in <filepath>reference</filepath> , <filepath>refbody</filepath> replaces the more general <filepath>body</filepath>.</li>
137	<li>A split row with a blank cell: The new specializations are in addition to the more general element, which remains available in the specialized type. For example, <filepath>reference</filepath> adds properties as a special type of simpletable ( <filepath>dl</filepath>), but the general kind of <filepath>simpletable</filepath> remains available in <filepath>reference</filepath>.</li>
138	</ul></dd>
139	</dlentry>
140	</dl>
141	</section>
142	<section>
143	<title>The reference type module</title>
144	<p>Listing 1 illustrates not the actual <userinput>reference.mod</userinput> content, but a simplified version based on Table 1. The use of entities in the content models support domain specialization, as described in the domain specialization article.</p>
145	<pre spectitle="Listing 1. reference.mod"><!ELEMENT reference ((%title;), (%prolog;)?, (%refbody;),(%info-types;)* )>
146	<!ELEMENT refbody (%section; \| refsyn \| %simpletable; \| properties)*>
147	<!ELEMENT properties ((%sthead;)?, (%strow;)+) >
148	<!ELEMENT refsyn (%section;)* > </pre>
149	<p>Most of the content models declared here depend on elements or entities declared in <userinput>topic.mod</userinput>. Therefore, if <filepath>topic</filepath>'s structure is enhanced or changed, most of the changes will be picked up by <filepath>reference</filepath> automatically. Also the definition of <filepath>reference</filepath> remains simple: it doesn't have to redeclare any of the content that it shares with <filepath>topic</filepath>.</p>
150	</section>
151	<section>
152	<title>Adding specialization attributes</title>
153	<p>To expose the element mappings, we add an attribute to each element that shows its mappings to more general types.</p>
154	<pre spectitle="Listing 2. reference.mod (part 2)"><!ATTLIST reference class CDATA "- topic/topic reference/reference ">
155	<!ATTLIST refbody class CDATA "- topic/body reference/refbody ">
156	<!ATTLIST properties class CDATA "- topic/simpletable reference/properties ">
157	<!ATTLIST refsyn class CDATA "- topic/section reference/refsyn "> </pre>
158	<p>Later on, we'll talk about how to take advantage of these attributes when you write an XSL transform. See the appendix for a more in-depth description of the class attribute. </p>
159	</section>
160	<section>
161	<title>Creating an authoring DTD</title>
162	<p>Now that we've defined the type module (which declares the newly typed elements and their attributes) and added specialization attributes (which map the new type to its ancestors), we can assemble an authoring DTD.</p>
163	<pre spectitle="Listing 3. reference.dtd">
164	<!--Redefine the infotype entity to exclude other topic types-->
165	<!ENTITY % info-types "reftopic">
166	<!--Embed topic to get generic elements -->
167	<!ENTITY % topic-type SYSTEM "topic.mod">
168	%topic-type;
169	<!--Embed reference to get specific elements -->
170	<!ENTITY % reference-type SYSTEM "reference.mod">
171	%reference-type;
172	</pre>
173	</section>
174	</body>
175	</topic>
176	<topic id="APIxmp">
177	<title>Specialization example: API description</title>
178	<body>
179	<p>Now let's create a more specialized information type: API descriptions, which are a kind of (and therefore specialization of) reference topic:</p>
180	<fig>
181	<title>A more specialized information type, API description </title>
182	<image href="image/APIdescdiag.gif" alt="API description specialization hierarchy" height="192" width="286"/>
183	</fig>
184	<p>Table 3 shows part of the specialization for an information type called <filepath>APIdesc</filepath>, for API description. As before, each column represents an information type, with specialization occurring from left to right. That is, each information type is a specialization of its neighbor to the left. Each row represents a set of mapped elements, with more specific elements to the right mapping to more general equivalents to the left.</p>
185	<section>
186	<p>As before, each cell specializes the contents of the cell to its left:</p>
187	<ul>
188	<li>A blank cell: The element to the left is picked up by the new type unchanged. For example, <filepath>simpletable</filepath> and <filepath>refsyn</filepath> are available in an API description.</li>
189	<li>A full cell: The element to the left is replaced by a more specific one. For example, <filepath>APIname</filepath> replaces <filepath>title</filepath>.</li>
190	<li>A split row with a blank cell: New elements are added to the elements on the left. For example, the API description adds a <filepath>usage</filepath> section as a peer of the <filepath>refsyn</filepath> and <filepath>section</filepath> elements.</li>
191	</ul>
192	<table frame="all">
193	<title>Summary of APIdesc specialization</title>
194	<tgroup cols="3">
195	<colspec colnum="1" colname="col01" colwidth="*"/>
196	<colspec colnum="2" colname="col1" colwidth="*"/>
197	<colspec colnum="3" colname="col03" colwidth="*"/>
198	<thead>
199	<row>
200	<entry colname="col01"> Topic</entry>
201	<entry colname="col1"> Reference</entry>
202	<entry colname="col03"> APIdesc</entry>
203	</row>
204	</thead>
205	<tbody>
206	<row>
207	<entry> (topic.mod) </entry>
208	<entry> (reference.mod)</entry>
209	<entry> (APIdesc.mod)</entry>
210	</row>
211	<row>
212	<entry> topic </entry>
213	<entry> reference </entry>
214	<entry> APIdesc </entry>
215	</row>
216	<row>
217	<entry> title </entry>
218	<entry/>
219	<entry> APIname </entry>
220	</row>
221	<row>
222	<entry> body </entry>
223	<entry> refbody </entry>
224	<entry> APIbody </entry>
225	</row>
226	<row>
227	<entry colname="col01" morerows="1">simpletable</entry>
228	<entry colname="col1">properties</entry>
229	<entry colname="col03">parameters</entry>
230	</row>
231	<row>
232	<entry colname="col1"/>
233	<entry colname="col03"/>
234	</row>
235	<row>
236	<entry morerows="2"> section </entry>
237	<entry> refsyn</entry>
238	<entry/>
239	</row>
240	<row>
241	<entry colname="col1" morerows="1"/>
242	<entry/>
243	</row>
244	<row>
245	<entry colname="col03">usage</entry>
246	</row>
247	</tbody>
248	</tgroup>
249	</table>
250	</section>
251	<section>
252	<title>The APIdesc module</title>
253	<p>Here you can see that the content for an API description is actually much more restricted than the content of a general reference topic. The sequence of <filepath>syntax</filepath>, then <filepath>usage</filepath>, then <filepath>parameters</filepath> is now imposed, followed by optional additional sections. This sequence is a subset of the allowable structures in a reference topic, which allows any sequence of syntax, properties, and sections. In addition, the label for the <filepath>usage</filepath> section is now fixed as <filepath>Usage</filepath>, taking advantage of the spectitle attribute of section (which is there for exactly this kind of usage): with the spectitle attribute providing the section title, we can also get rid of the title element in usage's content model, making use of the predefined section.notitle.cnt entity.</p>
254	<pre spectitle="APIdesc.mod">
255	<!ELEMENT APIdesc (APIname, (%prolog;)?, APIbody,(%info-types;)* )>
256	<!ELEMENT APIname (%title.cnt;)*>
257	<!ELEMENT APIbody (refsyn,usage,parameters,(%section;)*)>
258	<!ELEMENT usage (%section.notitle.cnt;)* >
259	<!ATTLIST usage spectitle CDATA #FIXED "Usage">
260	<!ELEMENT parameters ((%sthead;)?, (%strow;)+)></pre>
261	</section>
262	<section>
263	<title>Adding specialization attributes</title>
264	<p>Every new element now has a mapping to all its ancestor elements. </p>
265	<pre spectitle="APIdesc.mod (part 2)">
266	<!ATTLIST APIdesc class CDATA "- topic/topic reference/reference APIdesc/APIdesc " >
267	<!ATTLIST APIname spec CDATA "- topic/title reference/title APIdesc/APIname " >
268	<!ATTLIST APIbody spec CDATA "- topic/body reference/refbody APIdesc/APIbody" >
269	<!ATTLIST parameters spec CDATA "- topic/simpletable reference/properties APIdesc/parameters ">
270	<!ATTLIST usage spec CDATA "- topic/section reference/section APIdesc/usage ">
271	</pre>
272	<p>Note that <filepath>APIname</filepath> explicitly identifies its equivalent in both reference and topic, even though they are the same (title) in both cases. In the same way, usage explicitly maps to section in both reference and topic. This explicit identification makes it easier for processes to keep track of complex mappings. Even if you had a specialization hierarchy 10 levels deep or more, the attributes would still allow unambiguous mappings to each ancestor information type.</p>
273	</section>
274	<section>
275	<title>Authoring DTDs</title>
276	<p>Now that we've defined the type module (which declares the newly typed elements and their attributes) and added specialization attributes (which map the new type to its ancestors), we can assemble an authoring DTD.</p>
277	<pre spectitle="APIdesc.dtd">
278	<!--Redefine the infotype entity to exclude other topic types-->
279	<!ENTITY % info-types "APIdesc">
280	<!--Embed topic to get generic elements -->
281	<!ENTITY % topic-type SYSTEM "topic.mod">
282	%topic-type;
283	<!--Embed reference to get more specific elements -->
284	<!ENTITY % reference-type SYSTEM "reference.mod">
285	%reftopic-type;
286	<!--Embed APIdesc to get most specific elements -->
287	<!ENTITY % APIdesc-type SYSTEM "APIdesc.mod">
288	%APIdesc-type;
289	</pre>
290	</section>
291	</body>
292	</topic>
293	<topic id="xformover">
294	<title>Working with specialization</title>
295	<body>
296	<p>After a specialized type has been defined the necessary attributes have been declared, they can provide the basis for the following operations:</p>
297	<ul>
298	<li>Applying a general style sheet or transform to a specialized topic type</li>
299	<li>Generalizing a topic of a specialized type (transforming it into a more generic topic type)</li>
300	<li>Specializing a topic of a general type (transforming it into a more specific topic type - to be used only when a topic was originally authored in specialized form, and has gone through a general stage without breaking the constraints of its original form) </li>
301	</ul>
302	</body>
303	<topic id="genxforms">
304	<title>Applying general style sheets or transforms</title>
305	<body>
306	<p>Because content written in a new information type (such as <filepath>APIdesc</filepath>) has mappings to equivalent or less restrictive structures in preexisting information types (such as <filepath>reference</filepath> and <filepath>topic</filepath>), the preexisting transforms and processes can be safely applied to the new content. By default, each specialized element in the new information type will be treated as an instance of its general equivalent. For example, in <filepath>APIdesc</filepath> the <filepath><usage></filepath> element will be treated as a topic <filepath><section></filepath> element that happens to have the fixed label <filepath>"Usage"</filepath>.</p>
307	<p>To override this default behavior, an author can simply create a new, more specific rule for that element type, and then import the default style sheet or transform, thus extending the behavior without directly editing the original style sheet or transform. This reuse by reference reduces maintenance costs (each site maintains only the rules it uniquely requires) and increases consistency (because the core transform rules can be centrally maintained, and changes to the core rules will be reflected in all other tranforms that import them). Control over reuse has moved from the author of the transform to the reuser of the transform.</p>
308	<p>The rest of this section assumes knowledge of XSLT, the XSL Transformations language.</p>
309	</body>
310	<topic id="genxform_reqs">
311	<title>Requirements</title>
312	<body>
313	<p>This process works only if the general transforms have been enabled to handle specialized elements, and if the specialized elements include enough information for the general transform to handle them.</p>
314	<section>
315	<title>Requirement 1: mapping attributes</title>
316	<p>To provide the specialization information, you need to add specialization attributes, as outlined previously. After you include the attributes in your documents, they are ready to be processed by specialization-aware transforms.</p>
317	</section>
318	<section>
319	<title>Requirement 2: specialization-aware transforms</title>
320	<p>For the transform, you need template rules that check for a match against both the element name and the attribute value. </p>
321	<pre spectitle="The specialization-aware interface"><xsl:template match="*[contains(@class," topic/simpletable "]">
322	<!--matches any element that has a class attribute that mentions
323	topic/simpletable-->
324	<!--do something-->
325	</xsl:template>
326
327	</pre>
328	</section>
329	</body>
330	</topic>
331	<topic id="xformoverride_xmp">
332	<title>Example: overriding a transform</title>
333	<body>
334	<p>To override the general transform for a specific element, the author of a new information type can create a transform that declares the new behavior for the specific element and imports the general transform to provide default behavior for the other elements. </p>
335	<p>For example, an <filepath>APIdesc</filepath> specialized transform could allow default handling for all specialized elements except <filepath>parameters</filepath>:</p>
336	<pre spectitle="A specialized transformation for APIdesc">
337	<xsl:import href="general-transform.xsl"/>
338	<xsl:template match="*[contains(@class," APIdesc/parameters "]">
339	<!--do something-->
340	<xsl:apply-templates/>
341	</xsl:template>
342	</pre>
343	<p>Both the preexisting <filepath>reference</filepath><filepath>properties</filepath> template rule and the new <filepath>parameters</filepath> template rule match when they encounter a <filepath>parameters</filepath> element (because the <filepath>parameters</filepath> element is a specialized type of <filepath>reference</filepath><filepath>properties</filepath> element), and its class attribute contains both values). However, because the <filepath>parameters</filepath> template is in the <i>importing</i> style sheet, the new template takes precedence.</p>
344	</body>
345	</topic>
346	</topic>
347	<topic id="xformgeneralize">
348	<title>Generalizing a topic</title>
349	<body>
350	<p>Because a specialized information type is also an instance of its ancestor types (an <filepath>APIdesc</filepath> is a <filepath>reference topic</filepath> is a <filepath>topic</filepath>), you can safely transform a specialized topic to one of its more generic ancestors. This upward compatibility is useful when you want to combine sets of documentation from two sources, each of which has specialized differently. The ancestor type provides a common denominator that both can be safely transformed to. This compatibility may also be useful when you have to feed topics through processes that are not specialization-aware. For example, a publication center that charges per document type or uses non-DTD-aware processes could be sent a generalized set of documents, so that they only support one document type or set of markup. However, wherever possible, you should use specialization-aware processes and transforms, so that you can avoid generalizing and process your documents in their more descriptive, specialized form.</p>
351	<p>To safely generalize a topic, you need a way to map from your information type to the target information type. You also need a way to preserve the original type in case you need round-tripping later.</p>
352	<p>The <filepath>class</filepath> attribute that was introduced previously serves two purposes. It provices:</p>
353	<ul>
354	<li>The information needed to map.</li>
355	<li>A way to preserve the information to allow round-tripping. </li>
356	</ul>
357	<p>Each level of specialization has its own set of class attributes, which in the end provide the full specialization hierarchy for all specialized elements. </p>
358	<p>Consider the <filepath>APIdesc</filepath> topic in Listing 11:</p>
359	<pre spectitle="A sample topic from APIdesc">
360	<APIdesc>
361	<APIname>AnAPI</APIname>
362	<APIbody>
363	<refsyn>AnAPI (parm1, parm2)</refsyn>
364	<usage spectitle="Usage">Use AnAPI to pass parameters to your process.
365	</usage>
366	<parameters >
367	...
368	</parameters>
369	</APIbody>
370	</APIdesc>
371	</pre>
372	<p>With the class attributes exposed (all values are provided as defaults by the DTD):</p>
373	<pre spectitle="The same sample topic from APIdesc, including the class attributes">
374	<APIdesc class="- topic/topic reference/reference APIdesc/APIdesc ">
375	<APIname class="- topic/title reference/title APIdesc/APIname ">AnAPI
376	</APIname>
377	<APIbody class="- topic/body reference/refbody APIdesc/APIbody ">
378	<refsyn class="- topic/section reference/refsyn ">AnAPI(parm1,
379	parm2)</refsyn>
380	<usage class="- topic/section reference/section APIdesc/usage "
381	spectitle="Usage">
382	<p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
383	</usage>
384	<parameters class="topic/simpletable reference/properties APIdesc/parameters ">
385	...
386	</parameters>
387	</APIbody>
388	</APIdesc>
389	</pre>
390	<p>From here, a single template rule can transform the entire <filepath>APIdesc</filepath> topic to either a <filepath>reference</filepath> or a generic <filepath>topic</filepath>. The template rule simply looks in the <filepath>class</filepath> attribute for the ancestor element name, and renames the current element to match.</p>
391	<p>After a transform to topic, it should look something like Listing 13:</p>
392	<pre spectitle="A transformed topic from APIdesc"><topic class="- topic/topic reference/reference APIdesc/APIdesc ">
393	<title class="- topic/title reference/title APIdesc/APIname ">AnAPI
394	</title>
395	<body class="- topic/body reference/refbody APIdesc/APIbody ">
396	<section class="- topic/section reference/refsyn ">AnAPI(parm1,
397	parm2)</section>
398	<section class="- topic/section reference/section APIdesc/usage "
399	spectitle="Usage">
400	<p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
401	</section>
402	<simpletable class="topic/simpletable reference/properties APIdesc/parameters ">
403	...
404	</simpletable>
405	</body>
406	</topic>
407	</pre>
408	<p>Even after generalization, specialization-aware transforms can continue to treat the topic as an <filepath>APIdesc</filepath>, because the transforms can look in the <filepath>class</filepath> attribute for information about the element type hierarchy.</p>
409	<p>From here, it is possible to round-trip by reversing the transformation (looking in the <filepath>class</filepath> attribute for the specializing element name, and renaming the current element to match). Whenever the <filepath>class</filepath> attribute doesn't list the target (the first <filepath>section</filepath> has no <filepath>APIdesc</filepath> value), the element is changed to the last value listed (so the first <filepath>section</filepath> becomes, accurately, a <filepath>refsyn</filepath>).</p>
410	<p>However, if anyone changes the structure of the content while it is a generic <filepath>topic</filepath> (as by changing the order of sections), the result might not be valid anymore under the specialized information type (which in the<filepath>APIdesc</filepath> case enforces a particular sequence of information in the <filepath>APIbody</filepath>). So although mapping to a more general type is always safe, mapping back to a specialized type can be problematic: The specialized type has more rules, which make the content specialized. But those rules aren't enforced while the content is encoded more generally.</p>
411	</body>
412	</topic>
413	<topic id="xformspecialize">
414	<title>Specializing a topic</title>
415	<body>
416	<p>It is relatively trivial to specialize a general topic if the content was originally authored as a specialized type. However, a more complex case can result if you have authored content at a general level that you now want to type more precisely.</p>
417	<p>For example, suppose that you create a set of reference topics. Then, having analyzed your content, you realize that you have a consistent pattern. Now you want to enforce this pattern and describe it with a specialized information type (for example, API descriptions). In order to specialize, you need to first create the target DTD and then add enough information to your content to allow it to be migrated. </p>
418	<p>You can put the specializing information in either of two places:</p>
419	<ul>
420	<li>Add it to the <filepath>class</filepath> attribute. You need to be careful to get the order correct, and include all ancestor type values.</li>
421	<li>Or give the name of the target element in an <filepath>outputclass</filepath> attribute, migrate based on that value, and add the <filepath>class</filepath> attribute values afterward.</li>
422	</ul>
423	<p>In either case, before migration you can run a validation transform that looks for the appropriate attribute, then checks that the content of the element will be valid under the specialized content model. You can use a tool like Schematron to generate both the validating transform and the migrating transform, or you can migrate first and use the specialized DTD to validate that the migration was successful. </p>
424	</body>
425	</topic>
426	</topic>
427	<topic id="schemas">
428	<title>Specializing with schemas</title>
429	<body>
430	<p>Like the XML DTD syntax, the XML Schema language is a way of defining a vocabulary (elements and attributes) and a set of constraints on that vocabulary (such as content models, or fixed vs. implied attributes). It has a built-in specialization mechanism, which includes the capability to restrict allowable specializations. Using the XML Schema language instead of DTDs would make it much easier to validate that specialized information types represent valid subsets of generic types, which ensures smooth processing by generic translation and publishing transforms. </p>
431	<p>Unlike DTDs, XML schemas are expressed as XML documents. As a result, they can be processed in ways that DTDs cannot. For example, we can maintain a single XML schema and then use XSL to generate two versions: <ul>
432	<li>An authoring version of it that eliminates any fixed attributes and any overridden elements</li>
433	<li>A processor-ready version of it that includes the class attributes that drive the translation and publishing transforms</li>
434	</ul></p>
435	<p>However, XML schemas are not yet popular enough to adopt wholeheartedly. The main problems are a lack of authoring tools, and incompatibilities between the implementations of an evolving standard. These problems should be remedied by the industry over the next year or so, as the standard is finalized and schemas become more widely adopted and supported.</p>
436	</body>
437	</topic>
438	<topic id="summary">
439	<title>Summary</title>
440	<body>
441	<p>You can create a specialized information type by using this general procedure:</p>
442	<ol>
443	<li>Identify the elements that you need.</li>
444	<li>Identify the mapping to elements of a more general type.</li>
445	<li>Verify that the content models of specialized elements are more restrictive than their general equivalents.</li>
446	<li>Create a type module file that holds your specialized element and attribute declarations (including the <filepath>class</filepath> attribute).</li>
447	<li>Create an authoring DTD file that imports the appropriate type modules.</li>
448	</ol>
449	<p>You can create specialized XSL transforms by using this general procedure:</p>
450	<ol>
451	<li>Create a new transform for your information type.</li>
452	<li>Import the existing transform that you want to extend.</li>
453	<li>Identify the elements that you need to treat specially.</li>
454	<li>Add template rules that match those elements, based on their <filepath>class</filepath> attribute content.</li>
455	</ol>
456	</body>
457	</topic>
458	<topic id="specrules">
459	<title>Appendix: Rules for specialization</title>
460	<body>
461	<p>Although you could create a new element equivalent for any tag in a general DTD, this work is useless to you as an author unless the content models that would include the tag are also specialized. In the <filepath>APIdesc</filepath> example, the <filepath>parameters</filepath> element is not valid content anywhere in <filepath>topic</filepath> or <filepath>reference</filepath>. For it to be used, you need to create valid contexts for parameters, all the way up to the topic-level container. To expose the <filepath>parameters</filepath> element to your authors, you need to specialize the following parts:</p>
462	<ul>
463	<li>A <filepath>body</filepath> element, to allow parameters as valid content (giving us <filepath>APIbody</filepath>)</li>
464	<li>A <filepath>topic</filepath> element, to allow the specialized body (giving us <filepath>APIdesc</filepath>)</li>
465	</ul>
466	<p>This domino effect can be avoided by using domain specialization. If you truly just want to add some new variant structures to an existing information type, use domain specialization instead of topic specialization (see <xref href="DITA-domains.xml">Specializing domains in DITA</xref>).</p>
467	<p>To ensure that the specialized elements are more constrained than their general equivalents (that is, that they allow a proper subset of the structures that the general equivalent allows), you need to look at the content model of the general element. You can safely change the content model of your specialized element as shown in Table A: </p>
468	<table frame="all">
469	<title>Summary of specialization rules </title>
470	<tgroup cols="3">
471	<colspec colnum="1" colname="col1" colwidth="1.00*"/>
472	<colspec colnum="2" colname="col2" colwidth="1.52*"/>
473	<colspec colnum="3" colname="col3" colwidth="3.71*"/>
474	<thead>
475	<row>
476	<entry colname="col1">Content type</entry>
477	<entry colname="col2">Allowed specialization</entry>
478	<entry colname="col3">Example (Special specializing General)</entry>
479	</row>
480	</thead>
481	<tbody>
482	<row>
483	<entry>Required</entry>
484	<entry>Rename only</entry>
485	<entry>
486	<pre><!ELEMENT General(a)></pre>
487	<pre><!ELEMENT Special(a.1)></pre>
488	</entry>
489	</row>
490	<row>
491	<entry>Optional (?)</entry>
492	<entry>Rename, make required, or delete</entry>
493	<entry>
494	<pre><!ELEMENT General(a?)></pre>
495	<pre><!ELEMENT Special(a.1?)>
496	<!ELEMENT Special(a.1)>
497	<!ELEMENT Special EMPTY></pre>
498	</entry>
499	</row>
500	<row>
501	<entry>One or more (+)</entry>
502	<entry>Rename, make required, split into a required element plus others, split into one or more elements plus others.</entry>
503	<entry>
504	<pre><!ELEMENT General(a+)></pre>
505	<pre><!ELEMENT Special(a.1+)>
506	<!ELEMENT Special(a.1)>
507	<!ELEMENT Special(a.1,a.2,a.3+,a.4*)>
508	<!ELEMENT Special(a.1+,a.2,a.3*)></pre>
509	</entry>
510	</row>
511	<row>
512	<entry>Zero or more (*)</entry>
513	<entry>Rename, make required, make optional, split into a required element plus others, split into an optional element plus others, split into one-or-more plus others, split into zero-or-more plus others, or delete</entry>
514	<entry>
515	<pre><!ELEMENT General(a*)></pre>
516	<pre><!ELEMENT Special(a.1*)>
517	<!ELEMENT Special(a.1)>
518	<!ELEMENT Special(a.1?)>
519	<!ELEMENT Special(a.1,a.2,a.3+,a.4*)>
520	<!ELEMENT Special(a.1?,a.2,a.3+,a.4*)>
521	<!ELEMENT Special(a.1+,a.2,a.3*)>
522	<!ELEMENT Special(a.1,a.2?,a.3)>
523	<!ELEMENT Special EMPTY></pre>
524	</entry>
525	</row>
526	<row>
527	<entry>Either-or</entry>
528	<entry>Rename, or choose one</entry>
529	<entry>
530	<pre><!ELEMENT General (a\|b)></pre>
531	<pre><!ELEMENT Special (a.1\|b.1)>
532	<!ELEMENT Special (a.1)></pre>
533	</entry>
534	</row>
535	</tbody>
536	</tgroup>
537	</table>
538	<section>
539	<title>Extended example</title>
540	<p>You have a general element <filepath>General</filepath>, with the content model <filepath>(a,b?,(c\|d+))</filepath>. This definition means that a <filepath>General</filepath> always contains element <filepath> a</filepath>, optionally followed by element <filepath>b</filepath>, and always ends with either <filepath>c</filepath> or one or more <filepath>d</filepath>'s.</p>
541	<pre spectitle="The content model for the general element General"><!ELEMENT General (a,b?,(c\|d+))></pre>
542	<p>When you specialize <filepath>General</filepath> to create <filepath>Special</filepath>, its content model must be the same or more restrictive: It cannot allow more things than <filepath>General</filepath> did, or you will not be able to map upward, or guarantee the correct behavior of general processes, transforms, or style sheets.</p>
543	<p>Leaving aside renaming (which is always allowed, and simply means that you are also specializing some of the elements that <filepath>Special</filepath> can contain), here are some valid changes that you could make to the content model of <filepath>Special</filepath>, resulting in the same or more restrictive content rules:</p>
544	<pre spectitle="A valid change to the model Special, making b mandatory"><!ELEMENT Special (a,b,(c\|d))></pre>
545	<p><filepath>Special</filepath> now requires <filepath>b</filepath> to be present, instead of optional, and allows only one <filepath>d</filepath>. It safely maps to <filepath>General</filepath>.</p>
546	<pre spectitle="A valid change to the model Special, making c mandatory and disallowing d"><!ELEMENT Special (a,b?,c)></pre>
547	<p><filepath>Special</filepath> now requires <filepath>c</filepath> to be present, and no longer allows <filepath>d</filepath>. It safely maps to <filepath>General</filepath>.</p>
548	<pre spectitle="A valid change to the model Special, making three specializations of d mandatory"><!ELEMENT Special (a,b?,d1,d2,d3)></pre>
549	<p><filepath>Special</filepath> now requires three specializations of <filepath>d</filepath> to be present, and does not allow <filepath>c</filepath>. It safely maps to <filepath>General</filepath>.</p>
550	</section>
551	<section>
552	<title>Details of the class attribute</title>
553	<p>Every element must have a class attribute. The class attribute starts and ends with white space, and contains a list of blank-delimited values. Each value has two parts: the first part identifies a topic type, and the second part (after a /) identifies an element type. The class attribute value should be declared as a default attribute value in the DTD. Generally, it should not be modified by the author. </p>
554	<p>Example: </p>
555	<pre><appstep class="- topic/li task:step bctask/appstep ">A specialized step</appstep></pre>
556	<p>When a specialized type declares new elements, it must provide a class attribute for the new element. The class attribute must include a mapping for every topic type in the specialized type's ancestry, even those in which no element renaming occurred. The mapping should start with topic, and finish with the current element type. </p>
557	<p>Example: </p>
558	<pre><appname class="- topic/kwd task/kwd bctask/appname "> </pre>
559	<p>This is necessary so that generalizing and specializing transforms can map values simply and accurately. For example, if task/kwd was missing as a value, and I decided to map this bctask up to a task topic, then the transform would have to guess whether to map to kwd (appropriate if task is more general, which it is) or leave as appname (appropriate if task were more specialized, which it isn't). By always providing mappings for more general values, we can then apply the simple rule that missing mappings must by default be to more specialized values, which means the last value in the list is appropriate. While this example is trivial, more complicated hierarchies (say, five levels deep, with renaming occurring at two and four only) make this kind of mapping essential.</p>
560	<p>A specialized type does not need to change the class attribute for elements that it does not specialize, but simply reuses by reference from more generic levels. For example, since task and bctask use the p element without specializing it, they don't need to declare mappings for it.</p>
561	<p>A specialized type only declares class attributes for the elements that it uniquely declares. It does not need to declare class attributes for elements that it reuses or inherits. </p>
562	</section>
563	<section>
564	<title>Using the class attribute</title>
565	<p>Applying an XSLT template based on class attribute values allows a transform to be applied to whole branches of element types, instead of just a single element type.</p>
566	<p>Wherever you would check for element name (any XPath statement that contains an element name value), you need to enhance this to instead check the contents of the element's class attribute. Even if the element is unrecognized, the class attribute can let the transform know that the element belongs to a class of known elements, and can be safely treated according to their rules.</p>
567	<p>Example:</p>
568	<pre>
569	<xsl:template match="*[contains(@class,' topic/li ')]">
570	This match statement will work on any li element it encounters. It will also work on step and appstep elements, even though it doesn't know what they are specifically, because the class attribute tells the template what they are generally.
571	<xsl:template match="*[contains(@class,' task/step ')]">
572	</pre>
573	<p>This match statement won't work on generic li elements, but it will work on both step elements and appstep elements; even though it doesn't know what an appstep is, it knows to treat it like a step.</p>
574	<p>Be sure to include a leading and trailing blank in your class attribute string check. Otherwise you could get false matches (without the blanks, 'task/step' would match on 'notatask/stepaway', when it shouldn't).</p>
575	</section>
576	<section>
577	<title>The class attribute in domains specialization</title>
578	<p>When you create a domains specialization, the new elements still need a class attribute, but should start with a "+" instead of a "-". This signals any generalization transforms to treat the element differently: a domains-aware generalization transform may have different logic for handling domains than for handling topic specializations. </p>
579	<p>Domain specializations should be derived either from topic (the root topic type), or from another domain specialization. Do not create a domain by specializing an already specialized topic type: this can result in unpredictable generalization behavior, and is not currently supported by the architecture. </p>
580	</section>
581	<section>
582	<title>Notices</title>
583	<lq>
584	<p>© Copyright International Business Machines Corp., 2002, 2003. All rights reserved.</p>
585	<p>The information provided in this document has not been submitted to any formal IBM test and is distributed "AS IS," without warranty of any kind, either express or implied. The use of this information or the implementation of any of these techniques described in this document is the reader's responsibility and depends on the reader's ability to evaluate and integrate them into their operating environment. Readers attempting to adapt these techniques to their own environments do so at their own risk. </p>
586	</lq>
587	</section>
588	</body>
589	</topic>
590	</topic>
591

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/libs/dita-ot-1.8.5/docsrc/articles/DITA-dsf.xml@ 99012

Download in other formats: