THL Toolbox > Developers' Zone > Web Development > THL Essays in Cocoon > THL Essays XML Mark-up Particulars
THL Essays XML Mark-up Particulars
This page covers the XML mark-up used in THL essays. For a description of the DTD declaration and TEI Header mark-up, see THL Essays XML Mark-up: File Names, DTD and TEIHeader. The following sections describe mark-up for structural divs, links, and images.
Div Structure
In previous versions of XML mark-up for THL, the div structure was not always logically applied. The new THL essays should on the contrary have a logical div structure. The body of any text marked up in TEI is contained in a single element <text>. This <text> element can have three children:
- front: <front>, this contains <div1> for each front sections, such as abstracts, or other preliminary sections. It is not required.
- body: <body>, this is a required element containing a <div1> for each sub-section. If the body is just one section of text, no <div1> is required. Introductory material (if it is not too long) can be contained in <p> elements preceding the first sub-section.
- sub-sections: The immediate sections of the <body> are created using <div1> elements. These in turn can have <div2>, which can have <div3>, and so on, up to <div7>. Should there be more levels than represented by <div7>, one should use the generic <div> element with the levels marked in the n attribute, thus, <div n="1">, <div n="2">, … etc. .... <div n="25">… ad infinitum.
- back: <back>, this contains <div1> elements for each back section such as glossary, bibliography, colophons, conclusions, etc.
Only the <body> element is required. In many instances, including most pre-existing THL essays, the <front> and <back> will not be used.
Major <div1> sections should have a unique id attribute assigned to them. The general principle for assigning internal <div1> id numbers is to use "a" for front, "b" for body, and "c" for back, followed by the sequential div number. Thus, the second section in the front would be "a2"; the third chapter in the body would be "b3", etc. <div2>s can be id-ed in a similar way adding their sequential number within their parent <div1>, thus the second sub-division of the fourth division (chapter) of the body, would be "b42". IDs are used to call up a particular section of an essay using a URL. So, if you want to link to a section in an essay, you must give its div an ID number.
Controlling the Section Numbering
To turn off the automatic numbering of the text's sections:
<text … rend="no-outline">
…
</text>this turns off all the automatic numbering.
To turn off just the <head> tag's auto-numbering, add rend="unnumbered" to the <head> tag itself.
External Links
All links that lead outside of THL must be recorded in the external links document. This document is found in:
- {thdl trunk}/texts/cocoon/essays/xml/external-links.dtd
It has the extension .dtd, because these are declarations included within the DTD declaration using an include, as described in the page on THL Essays XML Mark-up: File Names, DTD and TEIHeader. The bottom of the external-links.dtd document contains a list of links organized alphabetically by the entity name. There is a comment indicating the letter for each group. An example of such a declaration is:
                                                            <!-- H -->

<!ENTITY himart SYSTEM "http://www.himalayanart.org/" NDATA HTML>All links external to THL must be declared in this way. For sites that have searches or are database-backed, one does not need to declare an entity for each search but one can declare an entity for the search string without the search parameter value. Thus, there may be several links to the TBRC database, such as:
- Longchenpa's biographical record:
http://www.tbrc.org/kb/tbrc-detail.xq?RID=P1583 - Longchenpa's Seven Treasuries: http://www.tbrc.org/kb/tbrc-detail.xq?RID=W22920
- Longchenpa's birth place of g.yo ru stod grong: http://www.tbrc.org/kb/tbrc-detail.xq?RID=G967
For these a single entity can be declared for searching TBRC and the search parameter, the ID at the end, can be included as the n attribute of the link included in the XML. Thus, we do have the following entity declared:
                                                            <!-- T -->

<!ENTITY tbrc-search SYSTEM "http://tbrc.org/kb/tbrc-detail.xq?RID=" NDATA HTML >The link is then encoded as an <xref> element. The text inside the <xref> element contains the text of the hyperlink and if an n attribute is given, then its value is added to the end of the entity's URL. Thus, a simple link would be:
<xref doc="himart" type="url">Rubin Foundation's Himalayan Art Resources</xref>
Or, using the example above:
The <xref doc="tbrc-search" n="W22920" type="url">Seven Treasuries</xref> 
written by <xref doc="tbrc-search" n="P1583" type="url">Longchenpa</xref>
NOTE: for a link to any page on http://www.fpmt.org/, use the entity from the external-links.dtd file. In the XML file itself, you MUST add the attribute rend="_blank" to the <xref>.
Internal Links
All links to THL resources must be recorded in the internal links document. This document is found in:
- {thdl trunk}/texts/cocoon/essays/xml/internal-links.dtd
It has the extension .dtd, because these are declarations included within the DTD declaration using an include, as described in the page on THL Essays XML Mark-up: File Names, DTD and TEIHeader. The bottom of the internal-links.dtd document contains a list of links organized alphabetically by the entity name. There is a comment indicating the letter for each group. An example of such a declaration is:
                                                            <!-- T -->

 <!ENTITY thdl-places-mons-sera-herm SYSTEM "/places/monasteries/sera/hermitages/#essay=/cabezon/sera/herm/" NDATA HTML >The link is then encoded in the XML essay file as an <xref> element. The text inside the <xref> element contains the text of the hyperlink. Example:
View the <xref doc="thdl-places-mons-sera-herm" n="" type="url">Sera Hermitages</xref> project by José Cabezón.
If a resource has two or more child resources then create a single entity in the internal-links.dtd file and use the n attribute to specify the child resource (when an n attribute is given, its value is added to the end of the entity's URL). In the Sera Hermitages example, there are nineteen individual XML essays. To link to the XML essay on Chu bzang Hermitage:
The <xref doc="thdl-places-mons-sera-herm" n="chupzang" type="url">>Chupzang Hermitage</xref> is one of 
the Sera Hermitages that is a nunnery.
Images
Images are dealt with in a different way than before. All images should be stored in the Media Management System (MMS), which will assign the image a unique ID. Each image should be marked-up with a <figure> element whose "entity" attribute value is "thdl-mms-images". This entity is declared in the "internal-links.dtd" file. The n attribute of the image should be set to the MMS id for that particular image. The MMS id is the number at the end of the image's URL in the app itself. Thus, if you find the image at: http://mms.thdl.org/media/13630. The n attribute for its <figure> tag should be set to its ID, "13630". The rend attribute determines the placement of the image in the page. The caption for the image goes in a <figDesc> child of the <figure> tag. The caption can contain formatting mark-up as well. An example of the mark-up for an image is:
<figure entity="thdl-mms-images" n="13630" rend="left"> 
      <figDesc>Pilgrims from the Penbo region of Tibet pose for a picture in Sera, Tibet.</figDesc> 
</figure>
If no rend attribute (or "right") is given, the image is automatically floated right. The value of "left" floats the image left.
If two images are to be rendered side-by-side, then they are places in a <p> element with type="imgs" and an n attribute set to the maximum number of pixels width of the two images combined and one of the images is floated left using the rend="left" attribute, as follows:
<p rend="imgs" n="650"> 
   <figure entity="thdl-mms-images" n="13630" rend="left"> 
       <figDesc>Local worshippers make butter offerings into the butter-lamps in a chapel 
       of one of Sera’s regional houses (Sera-Tibet).</figDesc> 
   </figure> 
   <figure entity="thdl-mms-images" n="11898"> 
       <figDesc>A young Tibetan girl, art supplies in hand, about to enter one of Sera’s temples in Tibet.</figDesc> 
   </figure> 
</p>
(For archiving purposes follow this link for Old Instructions on Markup of Images Not included in the MMS.)
Tables
The header for the table, which has the title of the table:
<table rend="border" n="5"> 
  <head>Table 2.1. Number of Surveyed Households by County and Township</head>
The header row has <ow rend="head">; the stylesheet renders text in each cell in bold and in the center of the cell.
You can set the width or height of an individual cell with the following code:
<row rend="head"> 
  <cell role="data" rows="2" cols="1">County</cell> 
  <cell role="data" rows="1" cols="2">Township</cell> 
  <cell role="data" rows="1" cols="1">Number of Surveyed Households</cell> 
  <cell role="data" rows="1" cols="1">Percent of Total Surveyed</cell> </row>
The stylesheets automatically detect whether the data in a column is numerical or text. It renders numbers right-aligned and text left-aligned. To override this, in the second row (if there is no header row, then do this in columns in the first row):
- To render data in all cells of a column to the left, in the cell in the second row of that column (or if there is more than one <row rend="head">, the first non-head row), add rend="left"
- To render data in all cells of a column to the right, in the cell in the second row of that column (or if there is more than one <row rend="head">, the first non-head row), add rend="right"
In addition, one can add rend="left", rend="right", or rend="center" to the <table> tag or to an individual cell's <row> tag.
For the "footer" (the information below the table that has the source of the data, or has the text for an asterisk following a data entry in the table, and so forth), use this markup as the final row of the table:
<row role="footer"> 
   <cell><hi rend="weak">Note: Because one-hundred households were surveyed in each county, 
   county figures also represent percentages for individual counties.</hi></cell> 
</row>
This <row> will only have one <cell> in it.
Glossary Table
To include non-Tibetan in the <term lang="tib"> field:
<p id="entry33"> 
   <num n="tib-sort-order">ts0018</num> 
   <term lang="tib" rend="uni">དུ་འཐུལ་</term> 
   <term lang="tib" n="duntül" rend="wyl">du 'thul</term> <hi rend="normal">(spelling uncertain)</hi></term>