![[The HTML Writers Guild Logo]](../../images/lo-025.gif)
The HTML Writers Guild
| |
|
||
The poemsfrag.dtd can be either used alone or as a module in the gutpoem1.dtd. It has a simple top level structure, and a bottom level structure that accounts for most of the divisions of a book of poetry. If a new division is needed it is possible to use one of the attributes to 'modify' the element. The full 'poemsfrag' dtd can be obtained here
The top level structure of the poemsfrag document type is given as follows
<!ELEMENT poemsfrag (meta*,acknowledge?,toc*,(poem|simplesect|para)*,endmeta*)>
The following figure shows the top level structure of the poemsfrag.dtd. in graphical form.
These elements are designed to contain comments on either the markup or the original material. They may be referenced from any element using the 'ref' attribute of that element. Both the meta and the endmeta elements are empty elements. They have an 'id' and a 'content' attribute. The later contains the message, and the former must be used if the element is being referenced from within the document. Usually referenced elements will be at the end of the document. i.e. they will be endmeta elements. (For those of you who are wondering why they cannot have the same name, if they do have the same name an ambiguity error will arise in the validation process).
Here is the element and attribute declaration for the meta element.
<!ELEMENT meta EMPTY> <!ATTLIST meta content CDATA #REQUIRED id ID #IMPLIED >
The declarations for the endmeta element is similar.
This element can be used to provide a simple acknowledgement that is designed to be read by the public.
<!ELEMENT acknowledge (#PCDATA)>
The toc element can contain item and title elements. Use an attribute to distinguish different kinds of 'table of contents' defined by the toc element.
<!ELEMENT toc (item|title)*>
<!ELEMENT item (#PCDATA|title)*>
The poem element is the workhorse of the dtd, and contains all the verses and titles etc. The sub elements are described in more detail later on. The granularity was suitable for Robert Burns poetry. Other poets may require a greater or lesser granularity. If a greater granularity is required, use an attribute on a note element.
These elements are provided to give structure to any part of the document out side of the poetry. simplesect can contain para, title, and item elements. para elements can contain title elements. The both can of course contain #PCDATA.
<!ELEMENT para (#PCDATA|title)*>
<!ELEMENT simplesect (#PCDATA|title|para|item)*>
The poem element can contain only one title element, and this must be the first element, apart from an optional prenote element, and then can contain subtitle|tune|note|footnote|verse elements in any number and order. Footnotes are usually labeled as such by the author, notes are for any asides that do not fit into any of the other categories. If necessary use an attribute to further define them.
Here is the element declaration for the poem element.
<!ELEMENT poem (prenote*,title?,(subtitle|tune|note|footnote|verse)*)>
Here is a diagramatic representation of the code.
Verses can contain any number of lines.
<!ELEMENT verse (line)*>
This section gives a few guidelines on when to use the individual elements.
<!ELEMENT title (#PCDATA)>
Nearly all poems have a major title, and this almost inevitably occurs at the begining of the poem. For those rare occasions when there is some preceeding text, use the prenote element.
<!ELEMENT verse (line)*>
Verses contain lines of poetry. They do not contain notes or footnotes. These can be at the end of the verse.
<!ELEMENT line (#PCDATA)>
This element is always a child element of verse. It describes the line of poetry as the author intended it. Note that a long line of poetry may wrap on to another line in the e-text, but the line element is meant to depict the line as the original author intended it.
<!ELEMENT prenote (#PCDATA)>
Very rarely an inscription will come before the main title. Use this element when it does.
<!ELEMENT subtitle (#PCDATA)>
Poems often have subtitles right after the title. Longer poems will also have subtitles within them. Whether an insert in the text is a subtitle or a note is a judgement call left to the marker. Where the doubt is reasonable a ref attribute referencing an endmeta element can be employed
<!ELEMENT tune (#PCDATA)>
Many songs will have a suggested tune. It is worthwhile describing this as a seperate element.
<!ELEMENT note (#PCDATA)> <!ELEMENT footnote (#PCDATA)>
These are notes placed in the verse by the original author, or by a subsequent editor. A footnote is usually referenced (in e-texts a caret '^'is often used) and is often described as such. Other material is commonly a note. When to use one element or the other is a judgement call that is left to the marker.
The attributes are not often used. However every element can take optional attributes. The 'ref' attribute will be used most often for referring to a meta tag that has background information about the element in question. Make sure there is an element with the correct id present, otherwise an error will be thrown on validation. Here is an example:
<title ref="fn4">The Jolly Miller</title> ....... <endmeta id="fn4" content="The original e-text appears to contain errors. See endmarkup for a list of these"/>
The type and role attributes can both be used for giving added semanic meaning to elements.
<!ENTITY % stdatts "ref IDREF #IMPLIED id ID #IMPLIED type CDATA #IMPLIED role CDATA #IMPLIED class CDATA #IMPLIED" >
This is just put here for the sake of completeness, and is an account of the elements in the poemsfrag dtd not mentioned above.
Rather than have numerous different kinds of tile it is better to use the role or type attributes to distinguish their roles. e.g.
<title role="toc">1794</title> <item>...
According to the element declaration for a paragraph:
<!ELEMENT para (#PCDATA|title)*>
a single paragraph could contain humerous titles. This however would be a bad markup practice.
The rules of XML do NOT allow the following element declaration
<!ELEMENT para (title?,#PCDATA)>
However if a title is used in a paragraph, there should only be one, and it should always come first.
<!ELEMENT item (#PCDATA)>
The item element should only be used for an enumeration in a list
There is a tutorial available showing how this DTD can be used to mark-up a couple of poems of Robert Burns
![[Valid XHTML 1.0]](../../images/vh40x.gif){kind=small}