Make your own free website on Tripod.com

pattern.dtd
[rev 0.3 Beta 1998.06.25]

A Draft DTD for Documenting Patterns with XML

This is the 0.3beta 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_3_beta.html. Please send any comments, complaints or suggestions to rod@pg.net or rwald@hotmail.com.

Changes from Revision 0.2 [pat_dtd_0_2.html]:


<!--
###############################################################################
#  PATTERN.DTD                                                                #
###############################################################################
#   filename: pattern.dtd                                                     #
#                                                                             #
#   A draft Document Type Definition for writing patterns in XML.             #
#                                                                             #
#   Revision #0.3 beta 1998.06.25                                             #
#   Rodney Waldhoff <rod@pg.net>;<rwald@hotmail.com>                          #
###############################################################################
-->

<!--
###############################################################################
#  FRONT MATTER                                                               #
###############################################################################
#  This describes some meta-information about the pattern or language.        #
#  This section will likely be broken out to a seperated DTD for easy         #
#  replacement.                                                               #
###############################################################################
 -->
<!-- front.name: a switch to include or ignore the front matter 
                 declaration. 
                 You can override this value with 'IGNORE' to leave out the
                 standard front-matter declaration.
-->
<!ENTITY % usefront 'INCLUDE' >

<![%usefront;[ <!-- begin conditional section for front matter -->

<!-- front.name: the name of the front matter tag. 
                 Users can override this entity to use a different label for  
                 the <front> tag.
                 Parsers should look for the element with the attribute
                 pat.elttype  = "front", or alternately, resolve this
                 entity and use the name given here.
                 In general this entity can be ignroed.
 -->
<!ENTITY % front.name "front" >

<!-- front.content: the base content model for the front element. 
                    In general there should be no need to replace this entity.
                    (You can use front.content.custom instead.)
 -->
<!ENTITY % front.content "author*, version?, copyright?" >

<!-- front.content.custom: a "plugin" for extending the front content model.
                           Use this entity to add to the content model for the
                           "front" element.
                           Note that you'll need to add the connector (",").
  -->
<!ENTITY % front.content.custom "" >
<!ELEMENT %front.name; (%front.content; %front.content.custom;) >

<!-- ###################################################################### -->

<!--
   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>.
 -->
<!-- author.name: the name of the author tag. 
                  Users can override this entity to use a different label for  
                  the <author> tag.
                  Parsers should look for the element with the attribute
                  pat.elttype  = "author", or alternately, resolve this
                  entity and use the name given here.
                  In general this entity can be ignroed.
 -->
<!ENTITY % author.name "author" >

<!-- author.content: the base content model for the author element. 
                     In general there should be no need to replace this entity.
                     (You can use front.content.custom instead.)
 -->
<!ENTITY % author.content "((propername+, email*, url*, orgdescr*) 
                           | orgdescr)" >

<!-- author.content.custom: a "plugin" for extending the author content model.
                            Use this entity to add to the content model for the
                            "author" element.
                            Note that you'll need to add the connector 
                            (",","|").
  -->
<!ENTITY % author.content.custom "" >
<!ELEMENT %author.name; (%author.content; %author.content.custom;) >

<!--
   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 HTML entity URL, or the
      "anchor" element <A> (specifically <A HREF>?

    · 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 content of the tag is the text used for the link.

   Note that in HTML you can render all this as:
   <A HREF="mailto:__&subject=__&cc=__&bcc=__&body=__">content</A>

   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.

   Perhaps something like:

     <version date="Thu Jun 25 1998" 
              time="18:10:25 CDT" 
              revision="1.1 Beta"
              status="draft" />

   Is preferable?
 -->
<!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 conditional section for front matter -->

<!--
###############################################################################
####### 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*,
                     remark*
                   )
>

<!--
   The patsect entity simply declares the basic content model for a pattern section.
 -->
<!ENTITY % patsect "#PCDATA?,
                   thumbnail?,
                   programlisting*,
                   itemlist*,
                   patref*,
                   citeref*,
                   remark*
>

<!--
   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 <remark> element identifies a comment from the document author.
   Production renderings may choose not to display these remarks.

   The element indicates, in effect, an author's note to herself (or 
   other authors).

   · perhaps we should add attributes for identifing the author who made
     the remark? or should we leave inside
   · this is likely to be an "inline" element, rather than a full "block"
     element.
 -->
<!ELEMENT remark (#PCDATA)>

<!--
   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.

   Perhaps this should just be an attribute of the pattern tag?
 -->
<!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 referencing where the alias is used?
    · This cannot be an attribue of pattern, since we want to allow more than 
      aka.
    · Perhaps this should be an empty tag with an attribute?
      E.g.
      <aka content="The Other Name for this Patttern" />
      This might help reinforce that this is a value, rather than markup.
 -->
<!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.

   Perhaps keyword should be an empty tag, similiar to the HTML meta type?
   E.g.:
     <keyword content="The Key Word or Phrase" />
   This might help reinforce that this is a value, rather than markup.

   If we go that far, isn't "keywords" better, just like the HTML meta:
     <keyword content="KeyWordA,KeyWordB,Key Phrase" />

   The 'one keyphrase per tag' form is probably easier to parse.
 -->
<!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.3beta 29 June 1998
Rod Waldhoff
rod@pg.net · rwald@hotmail.com
My root Tripod page:
members.tripod.com/~rwald

Valid Netscape-HTML!