Thdl Essays Xml Mark-up: File Names, Dtd, And Teiheader
<h3 class="heading-h6"><a name="THLToolboxhomegtDevelopersZonegtWebDevelopmentgtTHLEssaysinCocoonTHDLEssaysinCocoongtTHLEssaysXMLMarkup58FileNamesDTDandTEIHeader" class="anchorpoint"></a><a href="/tools/wiki/home.html">THL Toolbox</a> > <a href="/tools/wiki/Developers%27%20Zone.html">Developers' Zone</a> > <a href="/tools/wiki/Web%20Development.html">Web Development</a> > <a href="/tools/wiki/THDL%20Essays%20in%20Cocoon.html">THL Essays in Cocoon</a> > THL Essays XML Mark-up: File Names, DTD, and TEIHeader</h3><p class="paragraph">
</p><h3 class="heading-h1"><a name="THLEssaysXMLMarkupFileNamesDTDandTEIHeader" class="anchorpoint"></a>THL Essays XML Mark-up: File Names, DTD, and TEIHeader</h3><p class="paragraph"><strong class="bold">Contributor(s):</strong> Nathaniel Grove</p><p class="paragraph">This page describes the basic mark-up for a new THL essay. The basic mark-up for essays is done in our modified version of TEI. The latest DTD is called <span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="http://www.thdl.org/global/xml/dtds/xtib3.dtd" target="rwikiexternal">xtib3.dtd</a></span>. This DTD must be declared at the top of the document and include an entity declaration for external links plus entities for each image. In particular, this page covers the location of files, the DTD declaration, and the TEI header. For more specific essay mark-up of divs, images, and links, see <a href="/tools/wiki/THDL%20Essays%20XML%20Mark-up%20Particulars.html">THL Essays XML Mark-up Particulars</a>.
</p><h3 class="heading-h2"><a name="NameandLocationofEssayFiles" class="anchorpoint"></a>Name and Location of Essay Files</h3><p class="paragraph">All XML files are found in the TDL trunk/texts/cocoon/xml in a folder named for the first letter of the author's last name. Thus, an essay by Jose Cabezon goes in trunk/texts/cocoon/xml/c/. If the folder has not yet been created, then you will need to create it.</p><p class="paragraph">The essay should be name as follows: <em class="italic">{last name of author}</em>-<em class="italic">{descriptive title}</em>.xml. Thus, there is cabezon-sera-monks.xml and cabezon-sera-herm-intro.xml. In the Cocoon call for these essays, the dashes can be replaced by slashes, as for example:</p><p class="paragraph"><span class="nobr"><img src="/" alt="external link: " title="external link"/><a href="http://staging.thdl.org/places/monasteries/sera/hermitages/#essay=/cabezon/sera/herm/intro" target="rwikiexternal">#essay=/cabezon/sera/herm/intro</a></span></p><p class="paragraph">There can be up to four dashes after the author's name. The link above will work from any TDL page and does not need to have any docroot prefaced before the hash symbol (#). The above link goes to a particular TDL page only by way of example.
</p><h3 class="heading-h2"><a name="DTDdeclaration" class="anchorpoint"></a>DTD declaration</h3><p class="paragraph">The top of each essay must have a DTD declaration. Within this declaration there must be a reference to the external link entity file called "external-links.dtd". This contains all links to site outside of TDL. An internal link entity file ("internal-links.dtd"), for links within TDL is also included here. Both files are always found one folder above where the essays are located. If an external glossary is used, then an entity declaring the file which contains the glossary is also included. This file should reside in a subfolder called "glossaries" to the folder that contains the XML essay file. An example DTD declaration is:</p><div class="code"><pre><?xml version=<span class="java-quote">"1.0"</span> encoding=<span class="java-quote">"UTF-8"</span>?>
<!DOCTYPE TEI.2 SYSTEM <span class="java-quote">"http://www.thdl.org/global/xml/dtds/xtib3.dtd"</span> [
<!ENTITY % extlinks SYSTEM <span class="java-quote">"../external-links.dtd"</span> >
%extlinks;
<!ENTITY % intlinks SYSTEM <span class="java-quote">"../internal-links.dtd"</span> >
%intlinks;
<!ENTITY glossary SYSTEM <span class="java-quote">"glossaries/cabezon-sera-herm-gloss.xml"</span>>
]></pre></div><p class="paragraph">
</p><h3 class="heading-h2"><a name="TEIHeader" class="anchorpoint"></a>TEI Header</h3><p class="paragraph">
The TEI header, <teiHeader>, contains the metadata for the essay. For TDL use, all the relevant data is found withing the <fileDesc> element, while language data, which is shared by all essays, is found in the <profileDesc> element. In both instances, common shared mark-up is imported from a separate entity file so that it can be changed/enhanced globally for all essays.
</p><h3 class="heading-h3"><a name="TheFileDescElement" class="anchorpoint"></a>The FileDesc Element</h3><p class="paragraph">The first element in the teiHeader is the <fileDesc> element. It contains three parts:
</p><ol><li>Title Statement</li>
<li>Publication Statement</li>
<li>Source Description</li></ol><p class="paragraph">These will be described below and the whole section will be followed by an example of a complete <fileDesc> section of XML.
</p><h3 class="heading-h4"><a name="TitleStatement" class="anchorpoint"></a>Title Statement</h3><p class="paragraph">The Title statement is found in a <titleStmt> element. It should contain <title>, <author>, and <date> tags.</p><p class="paragraph">The <title> tag should have language set to "eng" (or whatever the language is). It's level attribute should be set to "a" for article, and the first title should have its type set to "full". Should the article have a particularly long title that does not fit in headers. A second title element with type="brief" can be added containing an abbreviated version of the title.</p><p class="paragraph">The <author> element should contain a <name> element for each author of the article. Thus, a multi-authored article will have <em class="italic">one</em> <author> element with several <name> elements within it. Each <name> element can have an ID attribute set to the authors unique three initials, a key attribute and a reg attribute. If the reg attribute is set to "thdlparticipant", then the key attribute can have that person's TDL ID number (i.e., "per1190"). This will automatically cause the author's name to be linked to the TDL Participant page for that person. After all the author <name> elements and still within the <author> element, a <date> element should be included for the date to be displayed with the article, usually date written. All dates should be in the format of YYYY-MM-DD.
</p><h3 class="heading-h4"><a name="PublicationStatement" class="anchorpoint"></a>Publication Statement</h3><p class="paragraph">The publication statement is found in <publicationStmt> element. This contains the following:</p><ul class="star"><li><strong class="bold">id</strong>: This is in an <id type="thdl">. And is assigned a number using the automatic PID generator</li>
<li><strong class="bold">Responsibility statements</strong>: There can be several of these in <respStmt> tags. These contain a <resp> that describes what the person did, i.e. "Mark-up", "Phonetics", "Proofing", followed by a <name>. The same attributes for <name>, id, key and reg, can be applied here as described above for author. <em class="italic"><strong class="bold">Note</strong></em>: In order to "turn on" the phonetics viewing option, there has to be a <respStmt> with a <resp>Phonetics</resp>.</li>
<li><strong class="bold">An entity declaration for publication information</strong>: This is simply "&thdlpubinfo;" following the last <respStmt>. This includes a preformatted set of XML tags found in the external-links.dtd document. Should any of the THL publication information need to be changed. It can be changed in that document and the changes will cascade throughout all essays.</li>
<li><strong class="bold">Date of Publication</strong>: This is a simple <date> element, following the publication information entity above, with the date of publication in YYYY-MM-DD format.</li>
<li><strong class="bold">Availability</strong>: This section found in an <availability> element contains the breadcrumb links for the essay locating it logically in the THL site. It contains a paragraph (<p>) followed by a <bibl> with a type="thdlloc". In that <bibl>, there are a series of <xref>s that link to the different ancestor pages for the essay in the THL site. The first <xref> is the highest ancestor or portal page, the last <xref> is the immediate parent of the page. If the one or more of these parents have a rend attribute set to "home-link", that link or links will appear above the TOC as a back to home link. The doc attribute of each <xref> should have the name of an entity declared in the entity document that has the link to that THL page. See the link section below for more detail.</li></ul><p class="paragraph">
</p><h3 class="heading-h4"><a name="SourceDescription" class="anchorpoint"></a>Source Description</h3><p class="paragraph">This is a required element in the TEI header's fileDesc element. The <sourceDesc> in this case contains a single paragraph with a prose description of the source. For digital-borne essays, use "Essay written for digital publication on THL." Other descriptions can be used to fit other occasions.
</p><h3 class="heading-h4"><a name="ExampleFileDescription" class="anchorpoint"></a>Example File Description</h3><p class="paragraph">The following is an example of a relatively complete <fileDesc> element from Jose Cabezon's essay, "People at Sera":</p><div class="code"><pre><fileDesc>
<titleStmt>
<title lang=<span class="java-quote">"eng"</span> level=<span class="java-quote">"a"</span> type=<span class="java-quote">"full"</span>>Monks at Sera</title>
<author><name id=<span class="java-quote">"jic"</span> key=<span class="java-quote">"per1190"</span> reg=<span class="java-quote">"thdlparticipant"</span>>José Ignacio Cabezón</name>
<date>2004-03-01</date></author>
</titleStmt>
<publicationStmt>
<idno type=<span class="java-quote">"thdl"</span>>thdl-essay:3</idno>
<respStmt>
<resp>Mark-up</resp>
<name>Wilson Chen</name>
</respStmt>
<respStmt>
<resp>Edited Markup <span class="java-keyword">for</span> Cocoon Delivery</resp>
<name id=<span class="java-quote">"ndg"</span> key=<span class="java-quote">"per1190"</span> reg=<span class="java-quote">"thdlparticipant"</span>>Than Grove <date>2008-01-16</date></name>
</respStmt>
<respStmt>
<resp>Phonetics</resp>
<name id=<span class="java-quote">"snw"</span> key=<span class="java-quote">"per2591"</span> reg=<span class="java-quote">"thdlparticipant"</span>>Steve Weinberger <date>2008-02-02</date></name>
</respStmt>
&thdlpubinfo;
<date>2004-03-01</date>
<availability>
<p>
<bibl n=<span class="java-quote">"thdlloc"</span>>
<xref doc=<span class="java-quote">"thdl-places"</span>>Places</xref>
<xref doc=<span class="java-quote">"thdl-mons"</span>>Monasteries</xref>
<xref doc=<span class="java-quote">"thdl-sera"</span>>Sera Monastery Home</xref>
<xref doc=<span class="java-quote">"thdl-sera-people"</span> rend=<span class="java-quote">"home-link"</span>>Sera People Home</xref>
</bibl>
</p>
</availability>
</publicationStmt>
<sourceDesc>
<p>Essay written <span class="java-keyword">for</span> digital publication on THL.</p>
</sourceDesc>
</fileDesc></pre></div>