Rod Waldhoff rod@pg.net · rwald@hotmail.com
My root Tripod page: members.tripod.com/~rwald
pattern.dtd
[rev 0.2 1998.06.22]
A Draft DTD for Documenting Patterns with XML
This is the 0.2 version of Rod's pattern.dtd. Comments and a pointer to the most recent version can be found at members.tripod.com/~rwald/patterns/pat_dtd.html. (As of this writing, this is the most recent version.)
An example of using this DTD to mark-up a pattern, together with some example
renderings of that markup is available.
This document is members.tripod.com/~rwald/patterns/pat_dtd_0_2.html. Please send any comments, complaints or suggestions to rod@pg.net or rwald@hotmail.com.
Changes from Revision 0.1 [pat_dtd_0_1.html]:
<!--
###############################################################################
filename: pattern.dtd
A draft Document Type Definition for writing patterns in XML.
Revision #0.2 1998.06.22
Rodney Waldhoff <rod@pg.net>;<rwald@hotmail.com>
###############################################################################
-->
<!--
###############################################################################
######### Front Matter Information (not directly related to patterns) #########
###############################################################################
-->
<!--
############################### Author Related ################################
-->
<!--
The <author> element 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>.
-->
<!ELEMENT author ((propername+, email*, url*, orgdescr*) | orgdescr) >
<!--
The <propername> element 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*, suffix?, altpropername*) ) >
<!--
The <altpropername> element 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> elements identify the parts of
a proper name.
Note that suffix is intended for things like Jr., Sr., III, etc.
-->
<!ELEMENT surname (#PCDATA)>
<!ELEMENT firstname (#PCDATA)>
<!ELEMENT middlename (#PCDATA)>
<!ELEMENT suffix (#PCDATA)>
<!--
The <href> element identifies a cross-reference to an online document.
The url attribute identifies the address (which should include the
protocol specification (http:,ftp:wais:,etc.)).
The body of the element is the text that is linked, or a label to use.
Notes:
· How does this relate to the HTML3.2 DTD entity URL, or the
"anchor" element <A>?
· Should this element be replaced by some XLL structure?
-->
<!ELEMENT href (#PCDATA)>
<!ATTLIST href url #CDATA #required >
<!--
The <email> element specifies an email address.
In HTML, this is likely to be rendered as a mailto href.
Note that all email address attibutes allow comma separated lists
of addresses.
The to attribute specifies the RCPT TO part of the email.
The cc attribute allows the writer to specify the CC part of
of the email.
The bcc attribute allows the writer to specify the BCC part of
of the email.
The subject attribute allows the writer to specify the SUBJECT part of
of the email.
The body attribute allows the writer to specify the BODY part of
of the email.
The body of the tag is the text used for the link.
Notes:
· Should this element be replaced by some XLL structure?
· Is "addr" or "address" preferable to "to"?
· Is "rcpt to" preferable to "to"?
-->
<!ELEMENT email (#PCDATA)>
<!ATTLIST email to #CDATA #required
cc #CDATA #implied
bcc #CDATA #implied
subject #CDATA #implied
body #CDATA #implied
>
<!--
The <orgdescr> element 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> element names an organization.
-->
<!ELEMENT orgname (#PCDATA)> <!-- allow "ANY"? -->
<!--
############################# END Author Related ##############################
-->
<!--
############################ Versioning and Misc ##############################
-->
<!--
The <version> element indicates version information
-->
<!ELEMENT version (date?, time?, revision?) >
<!--
The <date> and <time> elements indicate date and time
Notes:
· _Surely_ there is a standard for these?
-->
<!ELEMENT date (#PCDATA)>
<!ELEMENT time (#PCDATA)>
<!--
The <revision> element indicates a version number or identifer.
-->
<!ELEMENT revision (#PCDATA)>
<!--
The <copyright> element indicates a copyright notice.
It may contain one or more hrefs for additional information.
-->
<!ELEMENT copyright (#PCDATA,href*)>
<!--
The <cite> element describes an external source.
Note:
· There is probably a standard for biblio references like this.
(I'm leaving it as "ANY" for now.)
-->
<!ELEMENT cite ANY>
<!ATTLIST cite id #ID #required>
<!--
The <citeref> element is used to create reference to a citation,
i.e. for footnotes or endnotes.
Note:
· There is probably a standard for biblio references like this.
(I'm leaving it as "ANY" for now.)
-->
<!ELEMENT citeref ANY>
<!ATTLIST citeref citeid #IDREF #required>
<!--
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> element 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*,
cite*
)
>
<!--
The patsect entity simply wraps the acceptable content of a pattern section.
-->
<!ENTITY % patsect "#PCDATA?, thumbnail?, programlisting*, itemlist*, patref*, citeref*>
<!--
The <thumbnail> element represents a brief summary, suitable for using in an
index or as a thumbnail description of the pattern.
-->
<!ELEMENT thumbnail (#PCDATA)>
<!--
The <programlisting> element indicates explict source code, similar to
the html <pre> element.
The codelang attribute identifies the programing language used.
(This might be useful if we want to do automated keyword coloring or
other parsing/manipulation.)
The caption attribute may be used to provide a title.
Notes:
· Should we enable xref to full source code listings?
-->
<!ELEMENT programlisting (#CDATA)>
<!ATTLIST programlisting codelang #CDATA #implied
caption #CDATA #implied>
<!--
The <patref> element represents a refernce to another pattern or subsection.
It is composed of
· a pattern name (or identifier?)
· an optional sub-section of the pattern
· zero or more relations that indicate how the other pattern relates
to this one
The relation attribute 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
The <patref> name was suggested by Brad Appleton, I originally had just
<pat>.
Notes:
· should use some XLL structure?
-->
<!ELEMENT patref (#PCDATA)>
<!ATTLIST patref pattern #CDATA #required <!-- should be IDREF ? -->
section xxx #implied <!-- where xxx is enum of sections? -->
relation #CDATA #implied
>
<!--
The <itemlist> element groups a list of items (similar to <ol> and <ul>
The <item> element 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
(Should we use html notation anyway? We can always display/use it
however we want).
· Despite being my personal preference, the <item> name is probably
a bad choice?
· Perhaps <enum> instead of <itemlist>?
· Attributes of itemlist similiar to ol, ul, etc.?
-->
<!ELEMENT itemlist (item+)>
<!ELEMENT item (%patsect)>
<!--
The <patname> element indicates the name of the pattern.
-->
<!ELEMENT patname (#PCDATA)>
<!--
The <aka> element indicates the other names for the pattern.
Note that exactly one alias is listed per element, multiple elements may be used.
Notes:
· Add attributes for refencing where the alias is used?
-->
<!ELEMENT aka (#PCDATA)>
<!--
The <keyword> element indicates a key word or phrase that may be useful in
catagorizing the pattern.
Note that exactly one word or phrase is listed per element,
multiple elements may be used to indicate multiple keywords.
-->
<!ELEMENT keyword (#PCDATA)>
<!--
The <abstract> element indicates a summary suitable for extracting to a summary
or table of contents.
-->
<!ELEMENT abstract (%patsect)>
<!--
The <intent> element indicates the intent section
(what the pattern hopes to achieve)
-->
<!ELEMENT intent (%patsect)>
<!--
The <context> element indicates the context section
(when/where the pattern is applicable)
-->
<!ELEMENT context (%patsect)>
<!--
The <motivation> element indicates the motivation section
(a narrative description of when the pattern might arise)
-->
<!ELEMENT motiviation (%patsect)>
<!--
The <indications> element indicates the indications section
(similar to <context>, when might the pattern be applied)
a synonym is "symptoms"
-->
<!ELEMENT indications (%patsect)>
<!--
The <applicablity> element indicates the applicablity section
(another variation on <indications> and <context>)
-->
<!ELEMENT applicablity (%patsect)>
<!--
The <problem> element indicates the problem section
(an explict statement of the problem)
-->
<!ELEMENT problem (%patsect)>
<!--
The <forces> element indicates the forces section
(forces involved in the problem/solution)
-->
<!ELEMENT forces (%patsect)>
<!--
The <solution> element indicates the solution section
(the proposed solution to the problem)
-->
<!ELEMENT solution (%patsect, participant*, collaboration*)>
<!--
Notes:
· should they be broken out of the <solution> element?
· i'm not so sure about participant and collaboration, are these
worth having?
-->
<!ELEMENT participant (%patsect)>
<!ELEMENT collaboration (%patsect)>
<!--
The <consequences> element indicates the consequences section
(the results of applying the solution to the problem)
-->
<!ELEMENT consequences (%patsect)>
<!--
The <resultingContext> element indicates the resulting context section
Notes:
· I suggest that this is too similiar to consquences, and should
be removed. Any thoughts?
-->
<!ELEMENT resultingContext (%patsect)>
<!--
The <rationale> element indicates the rationale section
(why the solution is a good choice)
Notes:
· too similar to consequences or discussion?
-->
<!ELEMENT rationale (%patsect)>
<!--
The <discussion> element 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 (%patsect)>
<!--
The <implementation> element 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 (%patsect)>
<!--
The <example> element indicates the example section.
Notes:
· see <implementation>
-->
<!ELEMENT example (%patsect)>
<!--
The <sampleCode> element indicates the sampleCode section.
Notes:
· see <implementation>
· how does this relate to <programlisting>?
-->
<!ELEMENT sampleCode (%patsect)>
<!--
The <knownUses> element indicates the known uses section.
(specific cases in which this pattern has been sucessfully applied)
Notes:
· do we need greater structure here?
-->
<!ELEMENT knownUses (%patsect)>
<!--
The <relatedPatterns> element indicates the related patterns section.
(similiar or related patterns)
Notes:
· relation to see also?
-->
<!ELEMENT relatedPatterns (%patsect)>
<!--
###############################################################################
################## END elements related to the pattern form ###################
###############################################################################
-->
| Rev. 0.2 22 June 1998 Rod Waldhoff rod@pg.net · rwald@hotmail.com My root Tripod page: members.tripod.com/~rwald |
|