forked from dita-ot/docs
-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathDITA-dsf.xml
591 lines (587 loc) · 49.8 KB
/
DITA-dsf.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
<?xml version='1.0' encoding='utf-8'?>
<!-- This file is part of the DITA Open Toolkit project hosted on
Sourceforge.net. See the accompanying license.txt file for
applicable licenses.-->
<!-- (c) Copyright IBM Corp. 2004, 2005 All Rights Reserved. -->
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="specarch" xml:lang="en-us">
<title>Specializing topic types in DITA</title>
<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>
<prolog>
<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>
<critdates>
<created date="23 February 2001"/>
</critdates>
<metadata>
<audience type="user" job="other" experiencelevel="general"/>
<category>General</category>
<keywords>
<keyword>DITA</keyword>
<keyword>XML</keyword>
<keyword>topic</keyword>
<keyword>information architecture</keyword>
<keyword>architectural forms</keyword>
<keyword>specialization</keyword>
<keyword>information type</keyword>
<keyword>document type</keyword>
<keyword>DTD</keyword>
<keyword>document metadata</keyword>
<keyword>documentation</keyword>
<keyword>technical writing</keyword>
<keyword>user assistance</keyword>
<keyword>helps</keyword>
</keywords>
</metadata>
</prolog>
<body>
<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>
<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>
<p>The examples used in this paper use XML DTD syntax and XSLT; if you need background on these subjects, see Resources. </p>
</body>
<topic id="archcontext">
<title>Architectural context </title>
<body>
<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>
<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>
<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>
</body>
</topic>
<topic id="specinfotypes">
<title>Specializing information types</title>
<body>
<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>
<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>
<image href="image/basediag.gif" alt="Base information types" height="74" width="300"/>
<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>
<image href="image/manydiag.gif" alt="Specialized information types" height="253" width="494"/>
<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>
<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>
<li>Reduces maintenance costs: each authoring group maintains only the elements that it uniquely requires</li>
<li>Increases compatibility: the core information types can be centrally maintained, and changes to the core types are reflected in all specializing types</li>
<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>
</ul> Any information-typed topic belongs to multiple types. For example, an API description is, in more general terms, a reference topic.</p>
</body>
</topic>
<topic id="refxmp">
<title>Specialization example: Reference topic</title>
<body>
<p>Consider the specialization hierarchy for a reference topic:</p>
<image href="image/reftopicdiag.gif" alt="Reference topic specialization hierarchy" height="89" width="230"/>
<section>
<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>
<table frame="all">
<title>Relationships between topic and a specialization based on it </title>
<tgroup cols="2">
<colspec colnum="1" colname="col01" colwidth="*"/>
<colspec colnum="2" colname="col1" colwidth="*"/>
<thead>
<row>
<entry colname="col01"> Topic </entry>
<entry colname="col1"> Reference</entry>
</row>
</thead>
<tbody>
<row>
<entry>(topic.mod) </entry>
<entry> (reference.mod)</entry>
</row>
<row>
<entry> topic </entry>
<entry> reference </entry>
</row>
<row>
<entry> title </entry>
<entry/>
</row>
<row>
<entry colname="col01"> body </entry>
<entry colname="col1"> refbody </entry>
</row>
<row>
<entry colname="col01" morerows="1">simpletable</entry>
<entry colname="col1">properties</entry>
</row>
<row>
<entry colname="col1"/>
</row>
<row>
<entry morerows="1"> section </entry>
<entry> refsyn</entry>
</row>
<row>
<entry colname="col1"/>
</row>
</tbody>
</tgroup>
</table>
<dl spectitle="How to interpret Table 1.">
<dlhead>
<dthd>Structure</dthd>
<ddhd>Associations</ddhd>
</dlhead>
<dlentry>
<dt>Columns</dt>
<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>
</dlentry>
<dlentry>
<dt>Rows</dt>
<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>
</dlentry>
<dlentry>
<dt>Cells</dt>
<dd>Each cell in a column represents the following possibilities in relation to the cell to its left: <ul>
<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>
<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>
<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>
</ul></dd>
</dlentry>
</dl>
</section>
<section>
<title>The reference type module</title>
<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>
<pre spectitle="Listing 1. reference.mod"><!ELEMENT reference ((%title;), (%prolog;)?, (%refbody;),(%info-types;)* )>
<!ELEMENT refbody (%section; | refsyn | %simpletable; | properties)*>
<!ELEMENT properties ((%sthead;)?, (%strow;)+) >
<!ELEMENT refsyn (%section;)* > </pre>
<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>
</section>
<section>
<title>Adding specialization attributes</title>
<p>To expose the element mappings, we add an attribute to each element that shows its mappings to more general types.</p>
<pre spectitle="Listing 2. reference.mod (part 2)"><!ATTLIST reference class CDATA "- topic/topic reference/reference ">
<!ATTLIST refbody class CDATA "- topic/body reference/refbody ">
<!ATTLIST properties class CDATA "- topic/simpletable reference/properties ">
<!ATTLIST refsyn class CDATA "- topic/section reference/refsyn "> </pre>
<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>
</section>
<section>
<title>Creating an authoring DTD</title>
<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>
<pre spectitle="Listing 3. reference.dtd">
<!--Redefine the infotype entity to exclude other topic types-->
<!ENTITY % info-types "reftopic">
<!--Embed topic to get generic elements -->
<!ENTITY % topic-type SYSTEM "topic.mod">
%topic-type;
<!--Embed reference to get specific elements -->
<!ENTITY % reference-type SYSTEM "reference.mod">
%reference-type;
</pre>
</section>
</body>
</topic>
<topic id="APIxmp">
<title>Specialization example: API description</title>
<body>
<p>Now let's create a more specialized information type: API descriptions, which are a kind of (and therefore specialization of) reference topic:</p>
<fig>
<title>A more specialized information type, API description </title>
<image href="image/APIdescdiag.gif" alt="API description specialization hierarchy" height="192" width="286"/>
</fig>
<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>
<section>
<p>As before, each cell specializes the contents of the cell to its left:</p>
<ul>
<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>
<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>
<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>
</ul>
<table frame="all">
<title>Summary of APIdesc specialization</title>
<tgroup cols="3">
<colspec colnum="1" colname="col01" colwidth="*"/>
<colspec colnum="2" colname="col1" colwidth="*"/>
<colspec colnum="3" colname="col03" colwidth="*"/>
<thead>
<row>
<entry colname="col01"> Topic</entry>
<entry colname="col1"> Reference</entry>
<entry colname="col03"> APIdesc</entry>
</row>
</thead>
<tbody>
<row>
<entry> (topic.mod) </entry>
<entry> (reference.mod)</entry>
<entry> (APIdesc.mod)</entry>
</row>
<row>
<entry> topic </entry>
<entry> reference </entry>
<entry> APIdesc </entry>
</row>
<row>
<entry> title </entry>
<entry/>
<entry> APIname </entry>
</row>
<row>
<entry> body </entry>
<entry> refbody </entry>
<entry> APIbody </entry>
</row>
<row>
<entry colname="col01" morerows="1">simpletable</entry>
<entry colname="col1">properties</entry>
<entry colname="col03">parameters</entry>
</row>
<row>
<entry colname="col1"/>
<entry colname="col03"/>
</row>
<row>
<entry morerows="2"> section </entry>
<entry> refsyn</entry>
<entry/>
</row>
<row>
<entry colname="col1" morerows="1"/>
<entry/>
</row>
<row>
<entry colname="col03">usage</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>The APIdesc module</title>
<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>
<pre spectitle="APIdesc.mod">
<!ELEMENT APIdesc (APIname, (%prolog;)?, APIbody,(%info-types;)* )>
<!ELEMENT APIname (%title.cnt;)*>
<!ELEMENT APIbody (refsyn,usage,parameters,(%section;)*)>
<!ELEMENT usage (%section.notitle.cnt;)* >
<!ATTLIST usage spectitle CDATA #FIXED "Usage">
<!ELEMENT parameters ((%sthead;)?, (%strow;)+)></pre>
</section>
<section>
<title>Adding specialization attributes</title>
<p>Every new element now has a mapping to all its ancestor elements. </p>
<pre spectitle="APIdesc.mod (part 2)">
<!ATTLIST APIdesc class CDATA "- topic/topic reference/reference APIdesc/APIdesc " >
<!ATTLIST APIname spec CDATA "- topic/title reference/title APIdesc/APIname " >
<!ATTLIST APIbody spec CDATA "- topic/body reference/refbody APIdesc/APIbody" >
<!ATTLIST parameters spec CDATA "- topic/simpletable reference/properties APIdesc/parameters ">
<!ATTLIST usage spec CDATA "- topic/section reference/section APIdesc/usage ">
</pre>
<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>
</section>
<section>
<title>Authoring DTDs</title>
<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>
<pre spectitle="APIdesc.dtd">
<!--Redefine the infotype entity to exclude other topic types-->
<!ENTITY % info-types "APIdesc">
<!--Embed topic to get generic elements -->
<!ENTITY % topic-type SYSTEM "topic.mod">
%topic-type;
<!--Embed reference to get more specific elements -->
<!ENTITY % reference-type SYSTEM "reference.mod">
%reftopic-type;
<!--Embed APIdesc to get most specific elements -->
<!ENTITY % APIdesc-type SYSTEM "APIdesc.mod">
%APIdesc-type;
</pre>
</section>
</body>
</topic>
<topic id="xformover">
<title>Working with specialization</title>
<body>
<p>After a specialized type has been defined the necessary attributes have been declared, they can provide the basis for the following operations:</p>
<ul>
<li>Applying a general style sheet or transform to a specialized topic type</li>
<li>Generalizing a topic of a specialized type (transforming it into a more generic topic type)</li>
<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>
</ul>
</body>
<topic id="genxforms">
<title>Applying general style sheets or transforms</title>
<body>
<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>
<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>
<p>The rest of this section assumes knowledge of XSLT, the XSL Transformations language.</p>
</body>
<topic id="genxform_reqs">
<title>Requirements</title>
<body>
<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>
<section>
<title>Requirement 1: mapping attributes</title>
<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>
</section>
<section>
<title>Requirement 2: specialization-aware transforms</title>
<p>For the transform, you need template rules that check for a match against both the element name and the attribute value. </p>
<pre spectitle="The specialization-aware interface"><xsl:template match="*[contains(@class," topic/simpletable "]">
<!--matches any element that has a class attribute that mentions
topic/simpletable-->
<!--do something-->
</xsl:template>
</pre>
</section>
</body>
</topic>
<topic id="xformoverride_xmp">
<title>Example: overriding a transform</title>
<body>
<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>
<p>For example, an <filepath>APIdesc</filepath> specialized transform could allow default handling for all specialized elements except <filepath>parameters</filepath>:</p>
<pre spectitle="A specialized transformation for APIdesc">
<xsl:import href="general-transform.xsl"/>
<xsl:template match="*[contains(@class," APIdesc/parameters "]">
<!--do something-->
<xsl:apply-templates/>
</xsl:template>
</pre>
<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>
</body>
</topic>
</topic>
<topic id="xformgeneralize">
<title>Generalizing a topic</title>
<body>
<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>
<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>
<p>The <filepath>class</filepath> attribute that was introduced previously serves two purposes. It provices:</p>
<ul>
<li>The information needed to map.</li>
<li>A way to preserve the information to allow round-tripping. </li>
</ul>
<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>
<p>Consider the <filepath>APIdesc</filepath> topic in Listing 11:</p>
<pre spectitle="A sample topic from APIdesc">
<APIdesc>
<APIname>AnAPI</APIname>
<APIbody>
<refsyn>AnAPI (parm1, parm2)</refsyn>
<usage spectitle="Usage">Use AnAPI to pass parameters to your process.
</usage>
<parameters >
...
</parameters>
</APIbody>
</APIdesc>
</pre>
<p>With the class attributes exposed (all values are provided as defaults by the DTD):</p>
<pre spectitle="The same sample topic from APIdesc, including the class attributes">
<APIdesc class="- topic/topic reference/reference APIdesc/APIdesc ">
<APIname class="- topic/title reference/title APIdesc/APIname ">AnAPI
</APIname>
<APIbody class="- topic/body reference/refbody APIdesc/APIbody ">
<refsyn class="- topic/section reference/refsyn ">AnAPI(parm1,
parm2)</refsyn>
<usage class="- topic/section reference/section APIdesc/usage "
spectitle="Usage">
<p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
</usage>
<parameters class="topic/simpletable reference/properties APIdesc/parameters ">
...
</parameters>
</APIbody>
</APIdesc>
</pre>
<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>
<p>After a transform to topic, it should look something like Listing 13:</p>
<pre spectitle="A transformed topic from APIdesc"><topic class="- topic/topic reference/reference APIdesc/APIdesc ">
<title class="- topic/title reference/title APIdesc/APIname ">AnAPI
</title>
<body class="- topic/body reference/refbody APIdesc/APIbody ">
<section class="- topic/section reference/refsyn ">AnAPI(parm1,
parm2)</section>
<section class="- topic/section reference/section APIdesc/usage "
spectitle="Usage">
<p class="- topic/p ">Use AnAPI to pass parameters to your process.</p>
</section>
<simpletable class="topic/simpletable reference/properties APIdesc/parameters ">
...
</simpletable>
</body>
</topic>
</pre>
<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>
<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>
<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>
</body>
</topic>
<topic id="xformspecialize">
<title>Specializing a topic</title>
<body>
<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>
<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>
<p>You can put the specializing information in either of two places:</p>
<ul>
<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>
<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>
</ul>
<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>
</body>
</topic>
</topic>
<topic id="schemas">
<title>Specializing with schemas</title>
<body>
<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>
<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>
<li>An authoring version of it that eliminates any fixed attributes and any overridden elements</li>
<li>A processor-ready version of it that includes the class attributes that drive the translation and publishing transforms</li>
</ul></p>
<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>
</body>
</topic>
<topic id="summary">
<title>Summary</title>
<body>
<p>You can create a specialized information type by using this general procedure:</p>
<ol>
<li>Identify the elements that you need.</li>
<li>Identify the mapping to elements of a more general type.</li>
<li>Verify that the content models of specialized elements are more restrictive than their general equivalents.</li>
<li>Create a type module file that holds your specialized element and attribute declarations (including the <filepath>class</filepath> attribute).</li>
<li>Create an authoring DTD file that imports the appropriate type modules.</li>
</ol>
<p>You can create specialized XSL transforms by using this general procedure:</p>
<ol>
<li>Create a new transform for your information type.</li>
<li>Import the existing transform that you want to extend.</li>
<li>Identify the elements that you need to treat specially.</li>
<li>Add template rules that match those elements, based on their <filepath>class</filepath> attribute content.</li>
</ol>
</body>
</topic>
<topic id="specrules">
<title>Appendix: Rules for specialization</title>
<body>
<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>
<ul>
<li>A <filepath>body</filepath> element, to allow parameters as valid content (giving us <filepath>APIbody</filepath>)</li>
<li>A <filepath>topic</filepath> element, to allow the specialized body (giving us <filepath>APIdesc</filepath>)</li>
</ul>
<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>
<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>
<table frame="all">
<title>Summary of specialization rules </title>
<tgroup cols="3">
<colspec colnum="1" colname="col1" colwidth="1.00*"/>
<colspec colnum="2" colname="col2" colwidth="1.52*"/>
<colspec colnum="3" colname="col3" colwidth="3.71*"/>
<thead>
<row>
<entry colname="col1">Content type</entry>
<entry colname="col2">Allowed specialization</entry>
<entry colname="col3">Example (Special specializing General)</entry>
</row>
</thead>
<tbody>
<row>
<entry>Required</entry>
<entry>Rename only</entry>
<entry>
<pre><!ELEMENT General(a)></pre>
<pre><!ELEMENT Special(a.1)></pre>
</entry>
</row>
<row>
<entry>Optional (?)</entry>
<entry>Rename, make required, or delete</entry>
<entry>
<pre><!ELEMENT General(a?)></pre>
<pre><!ELEMENT Special(a.1?)>
<!ELEMENT Special(a.1)>
<!ELEMENT Special EMPTY></pre>
</entry>
</row>
<row>
<entry>One or more (+)</entry>
<entry>Rename, make required, split into a required element plus others, split into one or more elements plus others.</entry>
<entry>
<pre><!ELEMENT General(a+)></pre>
<pre><!ELEMENT Special(a.1+)>
<!ELEMENT Special(a.1)>
<!ELEMENT Special(a.1,a.2,a.3+,a.4*)>
<!ELEMENT Special(a.1+,a.2,a.3*)></pre>
</entry>
</row>
<row>
<entry>Zero or more (*)</entry>
<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>
<entry>
<pre><!ELEMENT General(a*)></pre>
<pre><!ELEMENT Special(a.1*)>
<!ELEMENT Special(a.1)>
<!ELEMENT Special(a.1?)>
<!ELEMENT Special(a.1,a.2,a.3+,a.4*)>
<!ELEMENT Special(a.1?,a.2,a.3+,a.4*)>
<!ELEMENT Special(a.1+,a.2,a.3*)>
<!ELEMENT Special(a.1*,a.2?,a.3*)>
<!ELEMENT Special EMPTY></pre>
</entry>
</row>
<row>
<entry>Either-or</entry>
<entry>Rename, or choose one</entry>
<entry>
<pre><!ELEMENT General (a|b)></pre>
<pre><!ELEMENT Special (a.1|b.1)>
<!ELEMENT Special (a.1)></pre>
</entry>
</row>
</tbody>
</tgroup>
</table>
<section>
<title>Extended example</title>
<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>
<pre spectitle="The content model for the general element General"><!ELEMENT General (a,b?,(c|d+))></pre>
<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>
<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>
<pre spectitle="A valid change to the model Special, making b mandatory"><!ELEMENT Special (a,b,(c|d))></pre>
<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>
<pre spectitle="A valid change to the model Special, making c mandatory and disallowing d"><!ELEMENT Special (a,b?,c)></pre>
<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>
<pre spectitle="A valid change to the model Special, making three specializations of d mandatory"><!ELEMENT Special (a,b?,d1,d2,d3)></pre>
<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>
</section>
<section>
<title>Details of the class attribute</title>
<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>
<p>Example: </p>
<pre><appstep class="- topic/li task:step bctask/appstep ">A specialized step</appstep></pre>
<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>
<p>Example: </p>
<pre><appname class="- topic/kwd task/kwd bctask/appname "> </pre>
<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>
<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>
<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>
</section>
<section>
<title>Using the class attribute</title>
<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>
<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>
<p>Example:</p>
<pre>
<xsl:template match="*[contains(@class,' topic/li ')]">
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.
<xsl:template match="*[contains(@class,' task/step ')]">
</pre>
<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>
<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>
</section>
<section>
<title>The class attribute in domains specialization</title>
<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>
<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>
</section>
<section>
<title>Notices</title>
<lq>
<p>© Copyright International Business Machines Corp., 2002, 2003. All rights reserved.</p>
<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>
</lq>
</section>
</body>
</topic>
</topic>