This is our style guide for use in writing tutorials and exercises for the digital humanities courses on newtfire. We have taken Obdurodon’s style guide as our model with some alterations.
Begin with another similar file from anywhere in newtFire’s course pages for digital humanities, which you should pull from our newtfire-webDev GitHub repository. If your file is going to be a tutorial, its file name should always begin with the word explain
and continue in camelCase with the topic, like this: explainXpath.html or explainGitShell.html.
Update the page title in the <title> element inside the <head> with the title of your page as it will appear in the tab above the browser. In the tab, for example, our CSS tutorial is titled simply Explain CSS.
Include the full version of the title in <h1> tags as it will appear in the body of the webpage inside the body element, just after the SSI line. The full version of the title of our CSS page is Introduction to Cascading Stylesheets
.
The boilerplate at the top of the page is managed with an SSI, signalled just after the <body> element, and for pages on which I (Elisa Beshero-Bondar) am the author, it appears thus:
<!--#include virtual="top.html" -->
To indicate yourself as an author, create a variation on my SSI file, which you will find in the dh-courses-Common directory on the newtFire GitHub, which you should have forked before working. SSI files for guest- and student-authored pages all begin with topAuthor
followed by the guest author’s id in caps, like this: topAuthorRJP43.html. To create your own SSI that indicates your authorship of a page, open one of these SSI files, save it as topAuthorYOURID.html, and change the name and e-mail address in parentheses after the phrase Authored by:
as shown in the code below. The e-mail address is optional.
<div id="top"><div id="bannerImage"><a href="http://newtfire.org/dh/"><img
src="newt-mosaic4.png"
alt="NewtFire logo: a mosaic rendering of a firebelly newt"/></a></div>
<div id="title"><a href="http://newtfire.org">newtFire</a> <a href="http://newtfire.org/dh">{dh|ds}</a></div>
<div class="boilerplate"><span><strong>Authored by: </strong> Rebecca J. Parker (rjp43 at pitt.edu) <strong>Edited and maintained by: </strong> Elisa E. Beshero-Bondar
(ebb8 at pitt.edu) <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
<img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-sa/4.0/80x15.png" /></a>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"></a> <strong>Last modified:
</strong><!--#echo var="LAST_MODIFIED" -->. <a href="http://newtfire.org/firebellies.html">Powered by firebellies</a>.</span></div>
</div>
<hr/>
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. Note: I have not yet begun implementing <section> elements on my older pages, so you may not see them, but we should begin implementing them.
Top-level section titles should be tagged as <h3>, with <h4>, etc. used for levels of subsections.
As a rule, we will capitalize only the first word of a section or subsection title, plus any word that must always be capitalized (sentence case
). That is, we don’t
capitalize every word, or every significant word in subsection headings. Note: Our older pages are inconsistent in implementing this rule, so you can help by flagging the inconsistencies where you see them.
For apostrophes in text we use curly, rather than straight apostrophes (except in code examples, of course). Here is a handy site for copying curly apostrophes and quotations directly into your text.
For text other than book and article titles and not inside code blocks, ordinary text (such as speech) that should be rendered in quotation marks we use the HTML
<q> element. Our newtFire CSS renders this as curly
quotation marks, and it will properly nest single quotation marks inside double
ones if we have nested quotations.
For website and book titles, use the <cite> element, which will properly render the title in italics wtih a semantic element designed for citation in HTML5.
For titles of articles, short poems, or subsections of a website or book that would normally take quotations marks, add an @class attribute, thus: <cite class="sub">, which our CSS will render inside curly quotation marks.
For subtitles or quoted material inside a title (with a set of internal single-quotation marks), set a second <cite class="sub"> inside the first, and our CSS will properly render this in curly single quotation marks.
Use title case
on titles of works outside of newtFire. That means you should capitalize the first word and subsequently the important words in the title of websites or books or other texts, as in these examples: Shelley and his Circle and The Dictionary of Imaginary Places. Always capitalize the first word after an internal colon in a title: The Lord Chamberlain Regrets: A History of British Theatre Censorship. When presenting titles of books or websites, include a year of publication if available in parentheses following the title and outside of the <cite> tags the first time you present it in the page, like this: The Lord Chamberlain Regrets: A History of British Theatre Censorship (2004).
We don’t usually use the <i> or <b>
elements. For emphasis use the more semantically meaningful HTML tags <em> and
<strong>. For terms being introduced use
<dfn>.
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.
If we use a horizontal ellipsis, we should use the raw Unicode character for it (given above), rather than three periods. Note: We need to apply this on our older pages.
Eliminate extra space characters at the beginnings and ends of paragraphs, etc.
Occasionally, as in this house style guide, we indicate some specialized information as an aside, using smaller text. For this purpose, surround text in <span class="smaller">.
We usually write element names without a trailing slash, even if it’s an empty element,
unless we need to emphasize that it’s an empty element. Element names are
surrounded by angle brackets and when mentioning attribute names by themselves, these are preceded by an at-sign (as in @class.
Both are tagged as <code> elements. Attribute values are indicated in straight quotes, and these are the only instance when we use straight quotes in our documents.
When rendering examples of faulty code, surround the code with <span class="badCode">
<pre>To represent longer blocks of code running over multiple lines, we preserve their spacing and formatting by rendering these inside the <pre> element. We proceed this way: Paste the block of code inside the <pre> element (which will generate many errors in <oXygen/>). Then highlight to select just the block of code, and open the Find and Replace Window to use regular expressions to replace the left and right angle brackets with their character entities. (View page source here to see several examples.)To avoid having extra blank lines inside a <pre> element, we
write the <pre> start tag and </pre> end
tag alongside the relevant text, on the same line as the text. In other words,
instead of:
<pre> <?xml version="1.0" encoding="UTF-8"?>
we write:
<pre><?xml version="1.0" encoding="UTF-8"?>
Likewise, instead of:
</TEI>
</pre>
we write:
</TEI><pre>
<oXygen/>
We write the name of our XML editor as <oXygen/>, with the angle brackets and slash.