Obdurodon style manual

Maintained by: David J. Birnbaum (djbpitt@gmail.com)

Last modified: 2023-01-20T19:32:23+0000

File boilerplate and filenames

Boilerplate

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="http://www.w3.org/1999/xhtml">
    <!--#set var="title" value="Page title goes here" -->
    <!--#config timefmt="%Y-%m-%dT%X%z" -->
    <head>
        <title><!--#echo var="title" --></title>
        <!--#include virtual="inc/dh-header.html" -->
    </head>
    <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.

Filenames

Lower-case only
Separate major filename parts (e.g., semester, test identifier, topic, whether it’s an answer key) with underscores. Separate minor parts (e.g., test-01, relax-ng) with hyphens.
Sample PDF test filename: 2224_test-01_xml.pdf
Sample HTML test filename: 2224_test-02_relax-ng.xhtml
Answer key is always HTML and adds _answers to basename of test, e.g., 2224_test-02_relax-ng_answers.xhtml
Ancillary files (e.g., the XML instance for a Relax NG test) are too varied to anticipate, but the naming should be consistent with the preceding

Markup

Sections and section titles

HTML5 has <section> elements, which are helpful to users with disabilities, so you should wrap <section> around each section (see http://www.smashingmagazine.com/2013/01/the-importance-of-sections/). 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.

Apostrophes

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">
<code>
<?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:
                </TEI>
</code>
</pre>
                we write:
                </TEI></code></pre>
                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">.

<oo>→<dh> Digital humanities