1 of 62

Publishing Editions on GitHub Pages

with the Text Encoding Initiative

Hugh Cayless, Raff Viglianti

Get this presentation:� http://bit.ly/2smyFut

​

​

2 of 62

Workshop structure

Part I

  • Introduction to text encoding �and the TEI
  • TEI customization
  • Using TEI for editorial work

Part II

  • Introduction to Git and GitHub
  • Creating static sites for �TEI documents
  • Basic styling and interaction
  • Publishing on GitHub Pages

First things first

​

Download Atom editor�https://atom.io/

Create a GitHub account�https://github.com/

Get this presentation: � http://bit.ly/2smyFut

3 of 62

Introduction to text encoding and the TEI

  • The TEI Guidelines may be found at http://www.tei-c.org/release/doc/tei-p5-doc/en/html/index.html
  • TEI looks very complicated, but you're not expected to use ALL of it. There's a lot to it, because texts are complex beasts and there are all kinds of ways you might want to model them.
  • YOU get to decide what parts of the TEI you need.
  • TEI is expressed in XML, which has some simple rules

4 of 62

XML Rules

  • XML files are plain text files
  • XML consists of elements, which can have attributes, and can contain other elements or text.
  • An element looks like <p>content</p> if it has content, or <lb/> if it doesn't.
  • Attributes on an element look like <div type="chapter" n="1">...</div>
    • Only on the opening tag
    • always in the form name="value"
  • XML elements can't overlap, so no <x><y></x></y>

​

5 of 62

XML Rules

  • There can be only one "root" element in an XML document
  • Sometimes you need to write special characters (like '<') in contexts that might be confusing (you don't want to confuse 'less than' with the start of an element), so XML provides 'escapes':
    • < = &lt;
    • > = &gt;
    • " = &quot;
    • ' = &apos;
    • & = &amp;
    • (these look weird for historical reasons)

6 of 62

XML Rules

  • If you break the rules, your document won't be "well-formed", and if you're using an XML editor, it will fuss at you.
  • XML also has structures that look like <?something?>. These are special directives.
  • <?xml version="1.0" encoding="UTF-8"?> is a pretty common one. Only shows up at the top of the document. It means: this is an XML document, following version 1.0 of the XML Specification, and it's Unicode, following the UTF-8 encoding.
  • <?xml-model href="schema.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?> is another common type. It's pointing at a schema for the document.

7 of 62

XML Schemas

  • Besides being well-formed, XML documents can also be "valid". That means besides the basic XML rules, they also follow rules specified in one or more separate documents, called a schema.
  • The whole point of TEI is to make it possible for you to make schemas that follow the TEI Guidelines and specify what can go in your documents.
  • Schemas can be in a few flavors: Relax NG and XML Schema are modern and fairly equivalent in power. There are also DTDs, which you may have heard of.
  • DON'T USE DTDs. It's legacy technology with all sorts of baggage.
  • Schematron is another schema language that permits more fine-grained rules. It's very common to have a Relax NG schema and a Schematron schema for the same document, because they're complementary.

8 of 62

TEI Documents

TEI documents always start with

<TEI xmlns="http://www.tei-c.org/ns/1.0">

They generally have a <teiHeader>, for metadata, and a <text> for the text content of your document.

The teiHeader contains things like title, date (of the TEI document), author/editor info, info about the source document(s), editorial practices, and revision history.

The text contains the text content along with whatever markup you want to use to model the structure and meaning of the document.

9 of 62

The Header

  • An example
  • Another example
  • The Guidelines page for teiHeader

​

10 of 62

The Text

  • What goes in the <text>?
    • Possibilities are infinite. What sorts of text are you dealing with, and what do you care about?
    • Structural elements: e.g., front, body, back, div, p (or ab), table, lg, and l
    • Elements that mark features of the source: e.g. gap, damage, unclear, hi
    • Elements that mark editorial interventions or interpretations: e.g. supplied, orig/reg, sic/corr, expan/abbr
    • Annotations on the text: e.g. persName, placeName, date, num
    • Textual variation: app, lem, rdg
    • "Specialty" stuff:
      • Linguistic annotation: s, cl, phr, w
      • Transcribed Speech, Dictionaries, Graphs
      • TEI Documentation

11 of 62

TEI customization

  • The TEI provides some schemas for you, including TEI All
    • Using TEI All is ok for experimentation, but is a bad idea for a project, because it lets you do everything. It's easy, but far from simple.
    • You might find a pre-built schema that suits your needs. Examples include EpiDoc or the DLL schema.
  • You probably want to make your own schema or take an example and modify it
    • Define custom value lists and taxonomies that suit your project
    • Include only the elements you want
    • Tighten up what's allowed where / add custom rules
    • Provide custom project documentation
  • A tutorial on creating ODDs (One Document Does it all)

12 of 62

Using TEI for editorial work

Setup Atom for use with TEI

Press Ctrl + , to access Settings > Install > search “linter-autocomplete-jing”

13 of 62

Using TEI for editorial work

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

<?xml-model href="http://www.tei-c.org/Vault/P5/current/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://relaxng.org/ns/structure/1.0"?>

<?xml-model href="http://www.tei-c.org/Vault/P5/current/xml/tei/custom/schema/relaxng/tei_all.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>

<TEI xmlns="http://www.tei-c.org/ns/1.0">

<teiHeader>

<fileDesc>

<titleStmt>

<title>Title</title>

</titleStmt>

<publicationStmt>

<p>Publication Information</p>

</publicationStmt>

<sourceDesc>

<p>Information about the source</p>

</sourceDesc>

</fileDesc>

</teiHeader>

<text>

<body>

<p>Some text here.</p>

</body>

</text>

</TEI>

​

Copy & paste this template� to get started

14 of 62

Using TEI for editorial work

Always check that your file is well-formed and valid

​

You can get suggestions for available elements

​

15 of 62

Using TEI for editorial work

Encoding textual structures

  • Most common TEI Elements are covered in this chapter of the Guidelines

<div> (text division)

Encodes a division of text, such as a chapter or a section

<p> (paragraph)

<lg> (line group)

Encodes a group of verses forming a formal unit, such as a stanza

<l> (verse line)

Encodes a line of verse (not a line of text; use <lb/> if you need to mark lines on a page)

​

16 of 62

Using TEI for editorial work

Encoding phrase-level text

  • Most common TEI Elements are covered in this chapter of the Guidelines
  • What are you interested in encoding about the text?

​

​

Mise-en-page is a term used by codicologists for the general layout and organization of the manuscript page.

Mise-en-page is a term used by codicologists for the general layout and organization of the manuscript page.

italic

foreign word

Procedural markup

Descriptive markup

17 of 62

Using TEI for editorial work

Encoding phrase-level text

  • What are you interested in encoding about the text?
    • Abbreviations and expansions�<abbr> <expan>
    • Highlights and quotations�<hi> <emph> <foreign>
    • Lists�<list> <item>
    • Verse and drama structures�<lg> <l> <sp> <speaker> <stage>
    • Names, dates, places�<name> <persName> <placeName>
    • Editorial intervention
    • Etc. etc.

​

​

18 of 62

Using TEI for editorial work

Some TEI elements for editorial work

  • Authorial revisions�<subst>� <add> </add> � <del> </del> �</subst>
  • Editorial intervention�<supplied> </supplied> �<choice> � <orig> </orig> <reg> </reg> �</choice>�<choice> � <sic> </sic> <corr> </corr> �</choice>
  • Variants�<app>� <lem wit=”#A”></rdg>� <rdg wit=”#B”></rdg>�</app>

​

19 of 62

Using TEI for editorial work - exercise

Choose a text to work on (more or less in order of difficulty)

  • A legible tombstone in Edenton, NC
    • Abbreviations, names, dates, unusual characters
  • Percy Shelley’s poem “To Laughter” (1816 Fair copy)
    • Manuscript, poetic structures, authorial revisions, misspelled words
  • Tombstone of Stephen Cabarrus in Edenton, NC
    • Supplied words and characters, editorial guesswork, names, dates
  • 1824 indenture form
    • Longer, print and handwriting, illegible text
  • Rough transcriptions of the above are available at https://github.com/hcayless/STS_workshop
  • Any other text

20 of 62

Break

☕

Get this presentation:� https://go.umd.edu/STS-TEI

21 of 62

Part II

Get this presentation:� https://go.umd.edu/STS-TEI

22 of 62

Introduction to Git and GitHub

file.xml

ADD

23 of 62

Introduction to Git and GitHub

file.xml

Version 4

Version 3

Version 2

Version 1

COMMIT

24 of 62

Introduction to Git and GitHub

file.xml

PUSH

REPOSITORY

25 of 62

Introduction to Git and GitHub

file.xml

PUSH

REPOSITORY

GitHub

26 of 62

Introduction to Git and GitHub

CLONE

27 of 62

Introduction to Git and GitHub

COMMIT

file.xml

Version 5

28 of 62

Introduction to Git and GitHub

COMMIT

PUSH

file.xml

Version 5

29 of 62

Introduction to Git and GitHub

PUSH

PULL

file.xml

Version 5

Version 4

Version 3

Version 2

Version 1

30 of 62

Introduction to Git and GitHub: summary

Git: a version control system GitHub: a social network of Git repositories

Add: add a new file to be tracked and versioned

Commit: save changes to a new version

Push: store files and their commits (versions) to a repository online

Repository: collection of files and their versions

Clone: recreate an online repository on your computer

Pull: get new changes from an online repository

31 of 62

Introduction to Git and GitHub

  • If you haven’t already, create a GitHub account on github.com
  • Download GitHub client at desktop.github.com
  • Clone repository at https://github.com/hcayless/STS_workshop
  • Make a change in README.md and commit it
  • Push to the online repository

32 of 62

Creating static sites for TEI documents

What is a static site?

A web page delivered to the user exactly as stored

What is it made of?

​

HTML

CSS

JAVASCRIPT

OTHER

ASSETS

33 of 62

Creating static sites for TEI documents

What is a static site?

A web page delivered to the user exactly as stored

What is it made of?

​

HTML

CSS

JAVASCRIPT

IMAGES

OTHER MEDIA

TEI

34 of 62

Creating static sites for TEI documents

MySite

css

data

js

texts

index.html

README.md

Create this folder structure

for your static site

Copy your TEI file into data

35 of 62

Creating static sites for TEI documents

Setup Atom for HTML preview

Press Ctrl + , to access Settings > Install > search “atom-html-preview”

36 of 62

Creating static sites for TEI documents

Open index.html in Atom

37 of 62

Creating static sites for TEI documents

A simple template for HTML 5 documents

<!doctype html>�<html lang="en">�� <head>� <title>My site</title> � <meta charset="utf-8">� <meta name="description" content="A site for my TEI">� <meta name="author" content="Me">� </head>�� <body>� <p>Hello world.</p>� </body>��</html>

Copy this to your index.html

38 of 62

Creating static sites for TEI documents

Add some content and preview with Ctrl + Shift + h

� <body>� <div>Hello, <i>world</i>!</div>� </body>

Hello, world!

39 of 62

Creating static sites for TEI documents

Rendering TEI files in your static site with

​

CETEIcean 🐳

HTML

CETEIcean

TEI

40 of 62

Creating static sites for TEI documents

Rendering TEI files in your static site with

​

CETEIcean 🐳

HTML

CETEIcean

TEI

The browser now treats TEI elements as if they were HTML

This is possible thanks to an

HTML5 technology called

“Custom Elements”

41 of 62

Creating static sites for TEI documents

Rendering TEI files in your static site with

CETEIcean 🐳

42 of 62

Creating static sites for TEI documents

Add CETEIcean to your index.html

� <head>� <title>My static site</title> � <meta charset="utf-8">� <meta name="description" content="A static site for my TEI">� <meta name="author" content="Me">�� <script src="js/CETEI.js"></script>�� </head>

Make sure to have both � opening and closing tags

43 of 62

Creating static sites for TEI documents

Run CETEIcean on your TEI file

STEP 1: Create a container for the TEI elements

<body>� <div>Hello, <i>world</i>!</div>� � <div id="TEI"></div>��</body>

You can remove this <div>

now if you want

44 of 62

Creating static sites for TEI documents

Run CETEIcean on your TEI file

STEP 2: Start CETEIcean

<body> � <div id="TEI"></div>�� <script>� var CETEIcean = new CETEI()� </script>��</body>

45 of 62

Creating static sites for TEI documents

Run CETEIcean on your TEI file

STEP 3: Run CETEIcean on your TEI file

<body> � <div id="TEI"></div>�� <script>� var CETEIcean = new CETEI()� CETEIcean.getHTML5('data/TEI.xml', function(data) {�� })� </script>��</body>

46 of 62

Creating static sites for TEI documents

Run CETEIcean on your TEI file

STEP 4: Add TEI data to the HTML container

<body> � <div id="TEI"></div>�� <script>� var CETEIcean = new CETEI()� CETEIcean.getHTML5("data/TEI.xml", function(data) {� document.getElementById("TEI").appendChild(data)� })� </script>��</body>

Remember to preview with

​

Ctrl + Shift + h

47 of 62

Basic styling and interaction

Let’s add some style

  • Use an existing CSS
  • Create your own!
  • ... or both! Use and existing CSS and add your specific changes
    • This is what we’ll do today

Cascading Style Sheets is a � language to style marked-up � documents

48 of 62

Basic styling and interaction

Let’s add some style

  • Download CETEIcean’s example CSS�
  • Save it to your css folder

49 of 62

Basic styling and interaction

Add CSS to your index.html

� <head>� <title>My static site</title> � <meta charset="utf-8">� <meta name="description" content="A static site for my TEI">� <meta name="author" content="Me">�� <script src="js/CETEI.js"></script>�� <link rel="stylesheet" href="css/CETEIcean.css"/>�� </head>

50 of 62

Basic styling and interaction

Let’s create a new CSS “style.css” for our own changes. Save it to css

� <head>� <title>My static site</title> � <meta charset="utf-8">� <meta name="description" content="A static site for my TEI">� <meta name="author" content="Me">�� <script src="js/CETEI.js"></script>�� <link rel="stylesheet" href="css/CETEIcean.css"/>� <link rel="stylesheet" href="css/style.css"/>�� </head>

51 of 62

Basic styling and interaction

Writing new styles

  • Basic CSS syntax

​

​

  • CETEIcean adds a tei- prefix to TEI elements to distinguish them from HTML ones�

div

{ color: red; text-align: center }

selector

declaration

tei-div

{ color: red; text-align: center }

selector

declaration

52 of 62

Basic styling and interaction

Let’s add a new style declaration for tei-supplied in style.css

tei-supplied {

​

font-style: italic;

​

}

Atom will suggest CSS � properties and values � as you type

Remember to preview with

​

Ctrl + Shift + h

53 of 62

Basic styling and interaction

Let’s add a new style declaration for tei-supplied in style.css

tei-supplied {

​

font-style: italic;

​

}

A pseudoselector

tei-supplied:before {

​

content: "["

​

}

tei-supplied:after {

​

content: "]"

​

}

54 of 62

Basic styling and interaction

Exercise: show a new page separator

TEI element: pb

What to style:

  • Display element as “block”
  • Add some width and height
  • Give it a background color

Use Atom’s suggestions to look through CSS properties and values as you type

55 of 62

Basic styling and interaction

Styling based on @rend attributes

Example: a drop cap

tei-seg[rend="decorInit"] {

font-size: 300%;

float: left;

line-height: 1em;

padding-right: 10px;

}

<p>� <seg rend="dropInit">T</seg>he� quick brown fox jumped over the� lazy dog.�</p>

he quick brown fox � jumped over the lazy dog.

T

56 of 62

Basic styling and interaction

Let’s add some interaction

  • Use JavaScript to dynamically change the CSS of TEI elements
  • We’ll see how to:
    • hide some stuff with CSS
    • create a “click” event
    • toggle visibility
  • Our case study: subst, add, and del

There are many ways of adding � interaction to a web page. � We’re just taking a quick dip!

57 of 62

Basic styling and interaction

Hide del in style.css, but only when its container is subst

Give add some color and a pointer cursor

tei-subst > tei-del {

display: none;

text-decoration: line-through;

}

tei-subst > tei-add {

color: blue;

cursor: pointer;

}

58 of 62

Basic styling and interaction

Now add interaction via JavaScript

<script>� var CETEIcean = new CETEI()� CETEIcean.getHTML5("data/TEI.xml", function(data) {� document.getElementById("TEI").appendChild(data)� � var substitutions = document.querySelectorAll("tei-subst")� substitutions.forEach( function(subst){� subst.querySelector("tei-add").addEventListener("click", function(){� var del = subst.querySelector("tei-del")� if (window.getComputedStyle(del).getPropertyValue("display") == "none") {� del.style.display = "inline"� }� else {� del.style.display = "none"� }�� })� })�</script>

This can be hard! Feel free to � copy and paste

59 of 62

Basic styling and interaction

Publishing on GitHub pages

Your static site is ready to go public!

  • add new files to Git
  • commit new files and changes
  • push to your online GitHub repository
  • Go to your repository’s GitHub page�https://github.com/USERNAME/PROJECT

60 of 62

Basic styling and interaction

Publishing on GitHub pages

  • Go to Settings
  • Turn on GitHub pages

61 of 62

Basic styling and interaction

Publishing on GitHub pages

  • Wait a little bit
  • Then visit your website!�https://USERNAME.github.io/PROJECT��
  • ​

🎉🎉🎉

62 of 62

Here is the address to complain

For TEI problems: https://github.com/TEIC/TEI/issues

For CETEIcean bugs: https://github.com/TEIC/CETEIcean/issues

Examples

http://teic.github.io/CETEIcean/

Digital Latin Library Critical Apparatus code: https://github.com/DigitalLatin/viewer / http://digitallatin.github.io/viewer/editio.html (may go away)

TEI Council Technical Working Papers: http://teic.github.io/TCW/