Digital humanities

Maintained by: David J. Birnbaum ( [Creative Commons BY-NC-SA 3.0 Unported License] Last modified: 2023-01-20T19:32:23+0000

Obdurodon style manual

This is a style guide for authoring course materials for Computational methods in the humanities.

File boilerplate and filenames


Boilerplate at the top of the page is managed with SSIs. Here’s a skeleton:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="">
    <!--#set var="title" value="Page title goes here" -->
    <!--#config timefmt="%Y-%m-%dT%X%z" -->
        <title><!--#echo var="title" --></title>
        <!--#include virtual="inc/dh-header.html" -->
    <body class="line-numbers">
        <!--#include virtual="inc/dh-boilerplate.html" -->

Type the page title only in the title variable configuration. Don’t enter it with header markup in the body; it will be inserted automatically as an <h2> when the SSI is resolved.

When you create a new page, copy and paste the preceding template at the top. When you edit an old page, open it from Dropbox instead of viewing the source in your browser and copying it. The source in your browser has SSIs already resolved, so the beginning of your file will be wrong.



Sections and section titles

HTML5 has <section> elements, which are helpful to users with disabilities, so you should wrap <section> around each section (see The <section> element has no effect on normal browser rendering.

The main page title, configured in the SSI described above, will be tagged as an <h2>, which means that top-level section titles should be tagged as <h3>, with <h4>, etc. used for levels of subsections.

We capitalize only the first word of a section title, plus any word that must always be capitalized (sentence case), and we do the same for book, article, and other publication titles when we refer to them. That is, we don’t capitalize every word, or every significant word (title case).

Presentational elements

For emphasis use <em> and <strong>. For terms being introduced use <dfn>. For book titles use <cite>. Use <i> and <b> when you want italic or bold and the semantics of the alternatives do not apply.

Whitespace and punctuation

White space

Watch out for extraneous space characters at the beginnings and ends of paragraphs, etc.

White space is preserved inside ]]> elements, which means that if you wrap a ]]> element to a new line and pretty-print, it will be rendered with the newline and indentation, which you probably don’t want unless it’s inside a ]]> element. We suggest configuring <oXygen/> not to pretty-print ]]> elements, which you can do with Options/Preferences → Editor → Format → XML → Elements Spacing, where you can add ]]> to the elements exempted from pretty-printing.


For apostrophes in text we use curly, rather than straight apostrophes (except in code examples, of course).

Horizontal ellipsis (…)

Horizontal ellipsis is represented by a single Unicode character, rather than three periods. You can copy and paste from the header, above; on MacOS you can enter a horizontal ellipsis from the keyboard with Option+;.

Hyphens and dashes

We distinguish hyphen (-), en dash (–), and em dash (—). Hyphen is used for hyphenated words, en dash is used for numerical ranges, and em dash is used to separate clauses. Do not put spaces around dashes, e.g., write this—not that instead of this — not that.

Quotation marks

For text that should be rendered in quotation marks we use the HTML <q> element. The Obdurodon CSS renders this as curly quotation marks, and it will properly nest single quotation marks inside double ones if we have nested quotations.

Markup for code blocks and code snippets

Code blocks using <pre>

Specify the language as a @class value of the ]]> element, most often ]]> (for any XML, including SVG and HTML). Our configuration also supports css, javascript, markdown, regex, and xquery (use xquery for both XQuery and XPath). You can’t combine (nest) these, so, for example, for XPath that includes regex specify xquery, etc.

When ]]> contains a code block it must have a single ]]> child element and the @class value that specifies the language type goes on the <pre> and not on the <code>. If, though, you use <pre> for plain-text or other non-code content, there should be no language @class value and no <code> child.

To avoid having extra blank lines inside a <pre> element, we write the ]]> start-tags and </code></pre> end-tags alongside the relevant text, on the same line as the text itself. In other words, instead of:

<pre class="language-xml">
<?xml version="1.0" encoding="UTF-8"?>

we write:

<pre class="language-xml"><code><?xml version="1.0" encoding="UTF-8"?>

Likewise, at the end of a <pre> section, instead of:


we write:


At the moment it is not possible to highlight inside a code block. Lines inside code blocks are numbered automatically when rendered, so you can refer to them by number in discussion.

Inline element references

Write element names inside prose surrounded by angle brackets, and without a trailing slash, even if it’s an empty element, unless we need to emphasize that it’s an empty element. Tag inline XML code snippets as <code class="language-xml">.

Inline attribute references

Inline attribute names are preceded by an at-sign and tagged as <code class="language-xquery">.

Inline XPath function references

Inline function references are followed by parentheses and tagged as <code class="language-xquery">.

Terminology and spelling


URLs should include the leading http:// or https://. That is, write instead of just

Markup and mark up

Markup (one word) is a noun (Great work on your markup!) that can be used as a modifier (XML is a markup language), but the verb is mark up, that is, two words (You should mark up your text according to the requirements of your research). That the one-word term markup isn’t a verb is why you wouldnt’t say We markuped our text.

Start- and end-tags

Start-tag and end-tag are technical terms and should be spelled accordingly. That means that we use the hyphen and we write start (not beginning or starting) and end (not closing or ending). The official name for a single self-closing empty-element tag is empty-element tag (hyphen between the first and second words and space between the second and third).

How to spell <oXygen/>

We write the name of our XML editor as <oXygen/>, with the upper-case X, angle brackets, and slash.

Change log