Getting Started

This is the outline of the 'Getting Started using TEI' document in the making. Chapter headings include the name of the person the chapter is currently assigned to. There is a separate page about the desired contents, style, setup, etc. of the document: About Getting Started. Here is the provisional result: [1]

Introduction (Peter)

TEI: a very high-level overview

• TEI: a set of guidelines, but also a community. 4p
• Why you would want to use TEI; explain the term 'encoding'; XML; what encoding entails; using an editor; validation; what you can then do with your document (transform it into other representations, have it searched; create selections). Possibilities for interchange and interoperability. 10p.

What this document does, and what it doesn't

• One paragraph explaining that this getting started document is more elaborate than many other documents with a similar name: that is because learning TEI is similar in effort and in reward to things like learning a new language or mastering a musical instrument: 1p
• Helps you get started, recognising that learning TEI is never going to be easy: 1p
• It is not: a full course in using xml, in tei, in xslt, in html: 1p
• Structure of the document. 2p
• Intended readership: 1p
• The reader is expected to have basic computer skills: create disk folders, move files, run programs, install programs, use unzip software. Not explain these, but just state you need the skills and suggest a way to acquire them. 2p.

Should you use TEI?

• Discuss nature of material, desired result, competence of encoder, available technical support, intellectual and practical benefits, effort to be expected, place of TEI in humanities computing: 12p

Technical background

• XML: explain a few basics, then refer to gentle XML introduction: 5p
• The web, web servers, html, browsers. One very simple HTML example, then point to other resources: 5p
• Even gentler intro into creating html from xml using xslt (mention but not discuss: pdf creation and other output formats): 5 p's

Overall structure of a TEI text

• Introduce sample document (without header), explain elements and attributes. 8p
• Add header. 5p

The rationale of declarative markup

• contrast declarative markup with wysiwyg editing: less susceptible to change, easily re-used in other contexts, unambiguous. 6p
• abstract approach towards texts that befits the scholar as it helps understand textual phenomena: 3p
• explain this again based on sample of drama markup. 4p

Choosing and installing an editor

• Point out that XML is application independent. This implies you can select an editor suited to the task at hand. You don't select an editor for the document's lifetime. 2p
• Discuss functions that an editor can handle: syntax highlighting, assisted entry, content completion, validation (dtd, w3c schema, relax ng), validation as you type, run xslt conversions, xslt debugging. Discuss source views: code view, wysiwyg view, tree view. Discussion illustrated with screen shots from multiple applications. 10 p
• Discuss a number of editors: .... Mention, but discourage from, option of using plain text editor. 10 p

Load, modify, validate a complete ready-made document

• This will be a document that we provide, together with a schema. Instructions for download. 2p
• Show number of functions of editor: 18 p (because of multiple editors)
  • different source views (maybe refer to oXygen video to explain editing in oXygen's author mode)
  • different side views: model, outline, attributes
  • find and replace
  • etc...

Running stylesheets

• Explain what XSLT is and what it does. 2p
• Installing XSLT processor, if not included in editor. 3p
• Discuss a simple stylesheet to transform the sample document, and based on this a number of xslt instructions. 10p
• Run the stylesheet and view the output. 2p
• Do some simple modifications. 2p
• Explain standard stylesheets. Download them. 4p
• Customise standard stylesheets: first using Stylebear, then by actually overriding some templates. 5p
• Running standard stylesheets. 1p

Getting this to work on sample of own text

• Preparing text in XML vs. converting prepared text to XML: argue it is better to use structured text from scratch. 3p
• Create an empty TEI document, using a template that we point to. 2p
• Fill in the blanks in the header. 2p
• Create a document snippet in the body. Validate. Generate HTML. 6p
• Urge reader to put up both HTML and XML on web site: is motivating, helps discussion with others, .... 3p

Schema's

• Explain the need for schema's that fit the texts. A few words about TEI conformance and TEI extensions. 4p
• Explain modules, classes, macro's. 6p
• Introducing ODD and Roma. Reference to 'Getting started with P5 ODD's. 6p
• Setting up ODD, (de)selecting elements and attributes. 3p
• Extension: creating a new element. Example: including tune indication for song. 3p
• Add documentation, save customisation, create new schema and use it for validation. 5p

Where to go from here

• What you probably need to do now: do document analysis, enter data, and create or modify a stylesheet that helps you display the data. 2p
• Document analysis: study the appropriate portions of the Guidelines, perhaps sets of local TEI guidelines developed elsewhere, discuss this with others, get help. Urge asking for feedback. 3p
• Enter data: if you have your texts in another format, it may help to learn some regular expressions: reference elsewhere. 2p
• Create or modify stylesheet: serious work on xslt stylesheets is not for everyone. 2p
• Places to look for tuition. 2p

Glossary

ODD 

One Document Does it all: document describing a TEI schema. See ...

HTML 

HyperText Markup Language, the language used to write web pages.

etc...

Literature

• References to other introductory material