Creating Textual Content in ESP XML Files

This page describes how to use the basic system-specific ESP elements and attributes to create web pages. It assumes that you know how to use Emacs and are familiar with the basics of HTML.

If you haven't already read the documentation on page structure in ESP then do so now. We also strongly recommend you read the ESP style guide.

Headings and subheadings

Including a short and enticing heading for each paragraph or section will help your reader to navigate around the page.

`<esp:h>`

The <esp:h> (heading) tag creates a heading and should be used instead of HTML's h1, which it replaces. It includes a bookmark that can be used by external websites to link to this point in the page.

<esp:h>
	Inline content
</esp:h>

If, say, your heading looks like this: <esp:h>Aims (and Objectives)</esp:h>, the processor will generate an HTML a element, with the values of the id and name attributes in lower-case, with a prefix h_ and without spaces or punctuation, like this: <a id="h_aimsandobjectives" name="h_aimsandobjectives"></a><h3>Aims</h3>, enabling other (non-ESP) websites to link to it with the a element in the usual way.

Within an ESP site, you can link to a heading using the esp:link element, setting the bookmark attribute like this: <esp:link page="whatever" bookmark="h_aimsandobjectives"/>.

`<esp:sh>`

Sub-headings for pages are created using the <esp:sh> (sub heading) tag which replaces HTML's h2. The sub-heading includes a bookmark that can be used by external websites to link to this point in the page.

<esp:sh>
	Inline content
>/esp:sh>

The <esp:sh> tag is the equivalent of using either <h1>, <h2> or <h3> tags in HTML.

If, say, your subheading looks like this: <esp:sh>Aims (and Objectives)</esp:sh>, the processor will generate an HTML a element, with the values of the id and name attributes in lower-case, <a id="h_aimsandobjectives" name="h_aimsandobjectives"></a><h3>Aims</h3>, enabling other (non-ESP) websites to link to it with the a element in the usual way.

Within an ESP site, you can link to a heading using the esp:link element, setting the bookmark attribute like this: <esp:link page="whatever" bookmark="h_aimsandobjectives"/>.

Tables

You can create tables using the usual HTML tags, and optionally add the attribute <table class="pretty"> to style it more elegantly.

Special characters

The characters >, > and & have special meanings in XML (single and double quotes do too, but only inside attribute values, if they then terminate those values). Therefore, if you need to use them in a web page, use the following named character entities as substitutes:

for & use & (ampersand);
for > use > (greater than);
for > use < (less than);
for " use " (use only in attribute values);
for ' use ' (use only in attribute values).

Note that no other named character entities (such as the non-breaking space,  ) are supported. Any character defined in HTML 4.01 can be used in ESP (see http://www.w3.org/TR/html401/sgml/entities.html [http://www.w3.org/TR/html401/sgml/entities.html] for a list). All can be specified as numeric character entities, such as   (the non-breaking space) or © (the copyright symbol, ©).

'Smart' or "smart" quotes, the ellipsis (...) character, and the en-dash (–) and em-dash (—) are automatically converted to 'dumb' or "dumb" quotes, three dots (...), and standard hyphens (-) for browser compatibility reasons.

To avoid errors, in any URLs that include the & (ampersand) character, substitute the entity & in place of the ampersand. Also see the documentation on Links.

Endmatter

Authors, updates and email addresses

The <esp:author> element defines an author for a page. It may be used any number of times, anywhere within the <body> element. If present at least once, author and citation details are included at the bottom of the content section.

<esp:author
	first-names="George W**ker"
	last-name="Bush"
/>

For multiple authors, use multiple <esp:author> elements:

<esp:author first-names="Example A." last-name="Author" />
<esp:author first-names="Example B." last-name="Author" />

Names will appear in the same order as the elements are listed. The example above will be displayed as: Example A. Author & Example B. Author

The <esp:content-last-modified/> element inserts the date the content of this page (i.e., the XML file inside 00web/) was last modified, in the format 18 Sep 2007.

The <esp:email address="me@example.com"/> element, which is always empty, creates an email address obfuscated like so – me at example dot com – which is converted back into a real address and made into a mailto: link using JavaScript, where available.

Accesskeys, sitemap etc.

<esp:accesskeys-listing/>

Creates a table of the access keys that are defined for the site in structure.xml, and those that are created automatically (such as S for Skip to main content). Probably used only once, on the accesskeys.xml page.

<esp:site-map/>

Creates a site map. Used once, on the sitemap.xml page. Always empty.

Comments

XML files can contain comments in this format: . Comments cannot be nested inside each other, because the sequence of characters -- is not permitted inside a comment.

Using comments can be handy way to temporarily remove sections of content from the site, as things that are commented out leave no trace in the final output site.

Next steps

There is an alphabetical reference list of ESP system elements for quick cross-reference.

There are also separate ESP help pages about:

18 Dec 2019 osc at oracc dot org

Ruth Horry & Eleanor Robson

Ruth Horry & Eleanor Robson, 'Creating Textual Content in ESP XML Files', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 [http://oracc.museum.upenn.edu/doc/help/portals/creatingcontent/]