-
Notifications
You must be signed in to change notification settings - Fork 0
/
parallel-design.xml
111 lines (88 loc) · 3.47 KB
/
parallel-design.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
<?xml version='1.0' encoding='UTF-8'?>
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0"
xreflabel="Parallel Design"
role="pattern">
<info>
<title>Parallel Design</title>
<abstract>
<para>Creating structures that for different elements that are very similar to one
another makes DTD easier to use and understand.</para>
</abstract>
</info>
<section>
<title>Problem</title>
<para>Authoring a document with complex structure can be difficult if there are many
elements, and each of these elements has their own particular content models.</para>
</section>
<section>
<title>Context</title>
<para>Any document that is large enough to be potentially difficult to learn.</para>
</section>
<section>
<title>Forces</title>
<para>Having consistency in the structure of document types makes document instances easier
to learn and process.</para>
</section>
<section>
<title>Solution</title>
<para>For elements that are similar in function use structures that are as close to
identical as possible.</para>
</section>
<section>
<title>Examples</title>
<programlisting language="dtd"><![CDATA[
<!ELEMENT Figure (Title, FigureBody, Number?)>
<!ATTLIST Figure height CDATA
width CDATA
id ID #REQUIRED>
<!ELEMENT Table (Title, TableBody, Number?)>
<!ATTLIST Table height CDATA
width CDATA
id ID #REQUIRED>
]]></programlisting>
<para>These two elements "Figure" and "Table" have very similar content
and identical attribute lists. This makes it very easy for authors of the document. Once
they have learned the structure of one of the elements, the other one will be easy to
use. The more variation there is between the two, the easier it is to confuse the two
structures.</para>
</section>
<section>
<title>Discussion</title>
<para>The more consistent the structure of various elements is the easier it is to learn to
use a document type. Subtle differences in structure can be particularly difficult to
learn. If, for example, in the above example, one of the "id" attributes was
IMPLIED and the other one was REQUIRED, this would be a difficult distinction to
remember. Users would constantly need to refer to the documentation to remind them which
element’s id was required and which one wasn’t.</para>
</section>
<section>
<title>Related Patterns</title>
<para>Often the parts of the structure that are the same between two elements can be
represented as <xref xl:href="../organization/flyweight.xml" />s.
This will help ensure that the two structures remain similar even through revisions of the document type.</para>
</section>
<section>
<title>Known Uses</title>
<para>The DocBook DTD defines these four entities:</para>
<programlisting language="xml">
<!ENTITY % div.title.content
"title, subtitle?, titleabbrev?">
<!ENTITY % bookcomponent.title.content
"title, subtitle?, titleabbrev?">
<!ENTITY % sect.title.content
"title, subtitle?, titleabbrev?">
<!ENTITY % refsect.title.content
"title, subtitle?, titleabbrev?">
</programlisting>
<para>All four of the elements have identical content model. This helps enormously in
learning the specifics of this DTD.</para>
</section>
<section>
<title>References</title>
<para>See Structuring XML Documents, Section 3.2.2.</para>
</section>
</section>