pattern.dtd
[rev 0.1 1998.06.18]
A Draft DTD for Documenting Patterns with XML
This is the 0.1 version of Rod's pattern.dtd. The most recent version can be found at
This document is
<!--
###############################################################################
filename: pattern.dtd
A draft Document Type Definition for writing patterns in XML.
Revision #0.1 1998.06.18
Rodney Waldhoff <rod@pg.net>;<rwald@hotmail.com>
###############################################################################
-->
<!--
###############################################################################
######### Front Matter Information (not directly related to patterns) #########
###############################################################################
-->
<!--
############################### Author Related ################################
-->
<!--
The <author> tag describes (one of) the document's author(s).
An author is either a person or an organization.
When an author is a person, the author section is composed of the following
elements:
· exactly one proper name <propername>
· zero or more email addresses <email>
· zero or more urls <url>
· zero or more descriptions of the author's organization <orgdescr>
When an author is an organization, the author section is composed of exactly
one <orgdescr>.
Notes:
· perhaps some description of urls is required, e.g. with a
label tag? eg, something like:
<url>
<address>http://www.isp.net/users/~me</address>
<label>My Personal Home Page</label>
</url>
<url>
<address>http://www.myCompany.com/employees/~me</address>
<label>My Corporate Bio Page</label>
</url>
· Does the <url> tag conflict with the HTML3.2 DTD entity URL?
-->
<!ELEMENT author ((propername+, email*, url*, orgdescr*) | orgdescr) >
<!--
The <propername> tag is used to identify a humans's proper name.
Note that the #PCDATA element is allowed for freeform data, but
<surname>,<firstname>,<middlename> is prefered.
Notes:
· Perhaps we should remove #PCDATA altogther?
· Is the propername format sufficently universal?
· Is there a better standard for this?
-->
<!ELEMENT propername ( (#PCDATA) |
(surname, firstname*, middlename*, altpropername*) ) >
<!--
The <altpropername> tag is used to specified aliases this person might have once
used, e.g., a maiden name, or to identify alternate spellings.
See <propername>.
-->
<!ELEMENT altpropername ( (#PCDATA) | (surname, firstname*, middlename*) ) >
<!--
The <surname>, <firstname> and <middlename> tags identify the parts of
a proper name.
-->
<!ELEMENT surname (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!--
The <url> tag identifies a Uniform Resource Locator, e.g. a web address.
It should include the protocol specification (http:,wais:,etc.).
Notes:
· perhaps some description of urls is required, e.g. with a
label tag? eg, something like:
<url>
<address>http://www.isp.net/users/~me</address>
<label>My Personal Home Page</label>
</url>
<url>
<address>http://www.myCompany.com/employees/~me</address>
<label>My Corporate Bio Page</label>
</url>
· Does the <url> tag conflict with the HTML3.2 DTD entity URL?
· Should this element be replaced by some XLL structure?
· Should #PCDATA really be #CDATA here?
-->
<!ELEMENT url (#PCDATA)>
<!--
The <email> tag specifies an email address.
In HTML, this is likely to be rendered as a mailto href.
Notes:
· Perhaps a labeling structure is needed to identify the email address,
e.g., something like:
<email>
<address>me@isp.net</address>
<label>My Personal Email Account</label>
</email>
<email>
<address>me@mycompany.com</address>
<label>My Business Email Account (preferred)</label>
</email>
· Should this element be replaced by some XLL structure?
· Should #PCDATA really be #CDATA here?
-->
<!ELEMENT email (#PCDATA)>
<!--
The <orgdescr> tag describes an organization.
Organizations must specify a name, and may provide zero or more urls.
· Is this data sufficient?
· Is there a need for more than one name?
· Perhaps allow for #PCDATA?
· Is there a better standard for this?
-->
<!ELEMENT orgdescr (orgname, url*)>
<!--
The <orgname> tag names an organization.
-->
<!ELEMENT orgname (#PCDATA)>
<!--
############################# END Author Related ##############################
-->
<!--
############################ Versioning and Misc ##############################
-->
<!--
The <version> tag indicates version information
-->
<!ELEMENT version (date?, time?, revision?) >
<!--
The <date> and <time> tags indicate date and time
Notes:
· _Surely_ there is a standard for these?
-->
<!ELEMENT date (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!--
The <revision> tag indicates a version number or identifer.
-->
<!ELEMENT revision (#PCDATA)>
<!--
The <copyright> tag indicates a copyright notice.
-->
<!ELEMENT copyright (#PCDATA)>
<!--
It seems like some xref to previous versions of a document would be useful.
Suggestions? Standards?
Utilizing XLL?
-->
<!--
########################## END Versioning and Misc ############################
-->
<!--
###############################################################################
####### END Front Matter Information (not directly related to patterns) #######
###############################################################################
-->
<!--
###############################################################################
##################### Elements related to the pattern form ####################
###############################################################################
-->
<!--
The <pattern> tag wraps a pattern.
It contains the standard pattern form elements, as well as some
meta-information about the author and revision.
The idea of nesting patterns was suggested by J.D. Fagan, who conjuctures the
existence of patterns that would not exist outside of the conext of another.
I think the idea is a good one.
-->
<!ELEMENT pattern ( patname,
aka*,
keyword*,
abstract?,
intent?,
context,
motivation?,
indications?,
applicablity?,
problem,
forces?,
solution,
consequences?,
resultingContext?,
rationale?,
discussion?,
implementation?,
example?,
sampleCode?,
knownUses?,
relatedPatterns?,
author*, <!-- should be + (one or more)? -->
version?,
copyright?,
pattern*
)
>
<!--
The patsect entity simply wraps the acceptable content of a pattern section.
-->
<!ENTITY % patsect "#PCDATA?, thumbnail?, programlisting?, patref*>
<!--
The <thumbnail> tag represents a brief summary, suitable for using in an
index or as a thumbnail description of the pattern.
-->
<!ELEMENT thumbnail (#PCDATA)>
<!--
The <programlisting> tag indicates explict source code, similar to
the html <pre> tag.
Notes:
· Should we enable xref to full source code listings?
-->
<!ELEMENT programlisting ((#CDATA),codinglanguage?>
<!--
The <codinglanguage> tag identifies the language for the code.
This might be useful if we want to do automated keyword coloring or
other parsing/manipulation.
Notes:
· The format is currently an undefined string. (should be "any"?)
-->
<!ELEMENT codinglanuage (#PCDATA)>
<!--
The <patref> tag represents a refernce to another pattern or subsection.
It is composed of
· a pattern name (or identifier?)
· an optional sub-section of the pattern
· an optional label to display (otherwise use the pattern name)
· zero or more relations that indicate how the other pattern relates
to this one
The <patref> name was suggested by Brad Appleton, I originally had just
<pat>.
Notes:
· should use some XLL structure?
-->
<!ELEMENT patref (patname, patsection?, label?, relation*)>
<!--
The <label> tag indicates the text to dispay (see <patref>).
-->
<!ELEMENT label (#PCDATA)>
<!--
The <patsection> tag indicates a section of a pattern form.
(see <patref>)
This should be an enumerated type, but I'll have to look up the syntax
-->
<!ELEMENT patsection (#PCDATA)>
<!--
The <relation> tag is used to indicate how the patterns relate.
(see http://www.geocities.com/SiliconValley/Horizon/3829/xml.htm for
examples of explict relations between patterns)
Some examples: variant, collaborator
Notes:
· XLL handles this as well!?!
-->
<!ELEMENT relation (#PCDATA)>
<!--
The enumpatsect entity simply wraps the acceptable content of a pattern
section that may contain an enumeration of elements (as in a "forces" section)
-->
<!ENTITY % enumpatsect "%patsect, item* >
<!--
The <item> tag represents an item in a list (similar to the html <li>
Notes:
· I suggest <item> rather than an html list, since we may choose to
represent the enumerated items in a different format
· Do we need a way of nesting/grouping items, other than the wrapping
pattern section?
· Despite being my personal preference, the <item> name is probably
a bad choice?
-->
<!ELEMENT item (#PCDATA)>
<!--
The <patname> tag indicates the name of the pattern.
-->
<!ELEMENT patname (#PCDATA)>
<!--
The <aka> tag indicates the other names for the pattern.
Note that exactly one alias is listed per tag, multiple tags may be used.
-->
<!ELEMENT aka (#PCDATA)>
<!--
The <keyword> tag indicates a key word or phrase that may be useful in
catagorizing the pattern.
Note that exactly one word or phrase is listed per tag,
multiple tags may be used to indicate multiple keywords.
-->
<!ELEMENT keyword (#PCDATA)>
<!--
The <abstract> tag indicates a summary suitable for extracting to a summary
or table of contents.
-->
<!ELEMENT abstract (%patsect)>
<!--
The <intent> tag indicates the intent section
(what the pattern hopes to achieve)
· should be enumpatsect?
-->
<!ELEMENT intent (%enumpatsect)>
<!--
The <context> tag indicates the context section
(when/where the pattern is applicable)
-->
<!ELEMENT context (%enumpatsect)>
<!--
The <motivation> tag indicates the motivation section
(a narrative description of when the pattern might arise)
-->
<!ELEMENT motiviation (%patsect)>
<!--
The <indications> tag indicates the indications section
(similar to <context>, when might the pattern be applied)
a synonym is "symptoms"
-->
<!ELEMENT indications (%enumpatsect)>
<!--
The <applicablity> tag indicates the applicablity section
(another variation on <indications> and <context>)
-->
<!ELEMENT applicablity (%enumpatsect)>
<!--
The <problem> tag indicates the problem section
(an explict statement of the problem)
-->
<!ELEMENT problem (%enumpatsect)>
<!--
The <forces> tag indicates the forces section
(forces involved in the problem/solution)
-->
<!ELEMENT forces (%enumpatsect)>
<!--
The <solution> tag indicates the solution section
(the proposed solution to the problem)
-->
<!ELEMENT solution (%enumpatsect, participant*, collaboration*)>
<!--
Notes:
· should they be broken out of the <solution> tag?
· i'm not so sure about participant and collaboration
-->
<!ELEMENT participant (%enumpatsect)>
<!ELEMENT collaboration (%enumpatsect)>
<!--
The <consequences> tag indicates the consequences section
(the results of applying the solution to the problem)
-->
<!ELEMENT consequences (%enumpatsect)>
<!--
The <resultingContext> tag indicates the resulting context section
Notes:
· I suggest that this is too similiar to consquences, and should
be removed. Any thoughts?
-->
<!ELEMENT resultingContext (%enumpatsect)>
<!--
The <rationale> tag indicates the rationale section
(why the solution is a good choice)
Notes:
· too similar to consequences or discussion?
-->
<!ELEMENT rationale (%enumpatsect)>
<!--
The <discussion> tag indicates the discussion section.
(commentary on how the solution resolves the forces)
Notes:
· too similar to consequences or rationale?
· any votes for <analysis>?
-->
<!ELEMENT discussion (%enumpatsect)>
<!--
The <implementation> tag indicates the implementation section.
(to me, this is a synonym for examples or sampleCode, but in GOF,
pitfalls, hints or techniques you should be aware of when implementing
the pattern)
-->
<!ELEMENT implementation (%enumpatsect)>
<!--
The <example> tag indicates the example section.
Notes:
· see <implementation>
-->
<!ELEMENT implementation (%enumpatsect)>
<!--
The <sampleCode> tag indicates the sampleCode section.
Notes:
· see <implementation>
· how does this relate to <programlisting>?
-->
<!ELEMENT sampleCode (%enumpatsect)>
<!--
The <knownUses> tag indicates the known uses section.
(specific cases in which this pattern has been sucessfully applied)
Notes:
· do we need greater structure here?
-->
<!ELEMENT knownUses (%enumpatsect)>
<!--
The <relatedPatterns> tag indicates the related patterns section.
(similiar or related patterns)
Notes:
· relation to see also?
-->
<!ELEMENT relatedPatterns (%enumpatsect)>
<!--
###############################################################################
################## END elements related to the pattern form ###################
###############################################################################
-->