Schema for Presentations
author: Syd Bauman
language: en-US
availability: Copyright 2006, 2007 Syd Bauman and Brown WWP Licensing: publicly available for copying, use, and distribution. Permission for direct modification is reserved; contact the author if you need to do this. On the other hand, permission to create your own ODD file based on a complete copy of this file is granted, so long as appropriate attribution is given. (E.g., copying the contents of this <fileDesc> into the <biblFull> of the new ODD's <sourceDesc>, then copying the entire <body> element into th

Yet Another Presentation System

Syd Bauman

A very tight TEI schema and associated stylesheets and scripts intended to be used to generate XHTML slides for teaching (you guessed it) TEI! The system is also capable of producing associated lecture notes (intended for instructor, but will be visible to students if source is visible to them) and handout notes (intended to be handed to students).

This document both describes and defines the schema, and also describes the usage of the stylesheets and scripts.

This TEI language is for making presentations. While it is primarily designed for making workshop presentations about TEI, it is likely applicable to lots of other situations.

The basic idea of this language is that a presentation (encoded as a <presentation>, the only child of <text>) consists of a series of one or more <section>s (so named because we couldn't think of a better name) which may or may not be grouped together via a <sectionGrp>.

The basic building blocks are the the children of <section>:

Basically, a presentation consists of a series of <section>s that have as their initial child a <slide>, or a series of <section>s that have as their initial child a <lectureNote>. In either case (<slide> first or <lectureNote> first), whichever element is first is required, and the other may follow optionally. In addition, a <handoutNote> may be the last child element of a <section>.

Some of the constraints of this language are expressed in Schematron. Thus it may be necessary to run two separate processes to validate an instance: one against a RELAX NG schema, and a second against a Schematron schema. (Note that oXygen will do this for you in one step.)

Notes on Usage

This section has some quickly spelled out notes on the expected usage of this language, most of which are not schema-enforced, but rather are expected by our current style-sheets.

- The @xml:lang attribute should not be specified as any language other than English on the <TEI> or <teiHeader> elements.
- Generally speaking, the date of the presentation should be in /TEI/teiHeader/fileDesc/publicationStmt/date. If a @value attribute is specified, it will be used; if not the content is used.
- The restriction that all <section> elements in a single <presentation> either have <slide> or <lectureNote> as their second child element (following <head>, which is required as the first child element) is not enforced by the schema, but rather by a Schematron rule. The RELAX NG schema permits intermingled slide-first or lecture-note-first sections.

Notes on Stylesheets

The stylesheets we use for generating slides, lecture notes, and handouts is …/stylesheets/yapsOut.xslt. For viewing the entire presentation directly in a browser the …/stylesheets/yaps-tei.css stylesheet may be used. For viewing the output XHTML for slides, lecture notes, and handout notes in a browser, the following stylesheets should be used, respectively:

- …/stylesheets/slides-html.css
- …/stylesheets/lecture-html.css
- …/stylesheets/handout-html.css

This section provides documentation that is relevant to these stylesheets, rather than the language and its schema.

To transform one or more input XML file conforming to this schema into XHTML slides at one time, use the yapsOut.bash command. The paths in this program are currently set for use on a Mac OS X system in which oXygen has been installed in the usual place (/Applications/oxygen/), or a Debian GNU/Linux system on which oXygen has been installed as the /usr/share/oxygen/ directory. [or any other system using the Debian SGML file hierarchy guidelines] To use on any other system edit the file and change the variables OXYGEN and stylesheet appropriately. The command to issue is
yapsOut.bash [-o /path/to/output/dir/] [-s SYSLIT] [-l]
            [-w] inFile1.xml inFile2.xml …
, where:

-s SYSLIT
- supplies the system literal to use for the XHTML (1.0 strict) DTD in the DOCTYPE of the output XHTML files; corresponds to the out-PubidLiteral parameter of the yapsOut.xslt stylesheet
-w
- shorthand for -s "", which causes the yapsOut.xslt stylesheet to use its default value, the canonical XHTML 1.0 Strict DTD from the W3C website as the system literal in the DOCTYPE declaration of the output XHTML files
-l
- uses the local copy of the XHTML 1.0 Strict DTD from the oXygen installation as the system literal in the DOCTYPE declaration of the output XHTML files; i.e., shorthand for -s /O2/frameworks/xhtml/dtd/xhtml1-strict.dtd, where O2 is the presumed path to the oXygen directory
-o path
- is the path to the directory for the output files; the default output directory is ./presentations/html/

yapsOut.xslt

- The <egXML> element is not in a usable state yet — it neither provides for validatable content nor looks pretty on output.
- The <table> and <figure> elements do not look pretty on output yet.
- The @rend attribute can be used on almost all phrase-level elements, and many others. Currently only two sets of values are recognized:

css(propVals)
- The CSS keyword (case insensitive) takes its propVals argument and passes it through to the XHTML as a @style= attribute. If propVals contains a parenthesis, it can be enclosed in square brackets or delimited by percent signs instead.
class(name)
- The class keyword (case insensitive) takes its name argument and passes it through to the XHTML as a @class attribute.

At the moment either css() or class() but not both can be specified. There is no theorhetical reason not to permit both, but we haven't done it yet.
- To point internally to somewhere else in the same document (e.g., to another slide), use <ptr>. Do not use <ptr> to point to an external document.
- To point to a document (or portion thereof) external to the presentation being written, use <ref>. Do not use <ref> to point internally.

slides-html.css

- The stylesheet has proper rendering of quotation marks for <mentioned>, <q>, <quote>, and <soCalled> when the parent element is in English, French, or German. It seems some browsers don't handle the nested quotation marks properly, though.

Instructions for Use with <oXygen/>

These are instructions for one method of transforming a file that conforms to this schema using the dedicated stylesheets and <oXygen/> 8.2 on a Mac OS X system.

- Create a transformation scenario, preferably named yapsOut.

- The XML URL should be ${currentFileURL}, indicating the currently edited file
- The XSL URL should be a pointer to or the path to the .../stylesheets/yapsOut.xslt file.
- Do not check the Use "xml-stylesheet" declaration box.
- Select Saxon8B as the tansformer.

- parameters, in alphabetical order

copyrightName
- Needed only if there is a problem — the stylesheet should extract this information from the <publicationStmt>.
copyrightYear
- Needed only if there is a problem — the stylesheet should extract this information from the <publicationStmt>.
cssPath
- Filepath to the directory that contains the CSS files slides-html.css, lecture-html.css, and handout-html.css. It may be a relative or absolute path or URI, depending on what your browser wants to see. It should end in a slash.
in-sourcePath
- Currently only used to pass the information on to the output XHTML in a <meta> element. Should be set to ${cfd}, which is the path of the current edited document up to and including the name of the parent directory, but not of the file itself.
logoFile
- The filepath of an image file (PNG or JPEG) to put in the corner of each slide. Default value is the file logo.png in the same directory as the input XML file.
logoSize
- Size of the logo image on the slide; current default is 32 pixels. Note that currently the stylesheet presumes the logo is (roughly) square. We can change this to height and width if needed.
out-baseFileName
- The name of the output files, to which _NN.xhtml will be appended. Generally should be set to the input filename with its extension, if any, removed; thus should be set to ${cfn}, which is the current filename without extension.
out-path
- The path of the folder into which the output files should be written. Defaults to ./presentations/html
out-PubidLiteral
- The FPI that will be put in the DOCTYPE declaration of the output XHTML files. Should generally be left to the default value.
out-SystemLiteral
- The SYSTEM identifier that will be put in the DOCTYPE declaration of the output XHTML files. For ease of use and for output that is easily portable, use the default, http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd. For files that load & validate faster and do not require a network connection but are not nearly as portable, use ${frameworks}/xhtml/dtd/xhtml1-strict.dtd.

- Leave all settings in Extensions, Append header and footer and Additional XSLT stylesheets empty or blank.
- Under the FO Processor tab make sure that Perform FO Processing is not checked.
- Under the Output tab select the Save As radio button, and fill in the path to a directory where the output should go. It does not matter wether or not there is an ultimate slash, but you will find that using the <oXygen/> dialog box (by clicking the little folder) only permits you to navigate to a file, not a directory.
- I have not tried Open in browser; I think Show As will not be helpful.

- When you run the transformation, you will get an error message: Cannot delete the file: {path-to-output-directory} prior to result generation.. Ignore it.
- The output XHTML files will go into the output directory indicated in the transformation scenario, overwriting any existing files with the same names.
- A junk output file will be created with the same name and path as the input file, but with _xslt appended. It should be deleted.
- To use output in browser or validate it in <oXygen/> you are done.
- If you want to validate the output XHTML files with a different tool (possibly including if you want to transform them), the SYSTEM literal needs to be fixed. <oXygen/> ouputs an absolute path (i.e., starts with a /) preceded by file:. From the commandline xmllint wants either file://, nothing, or just / to precede an absolute path. From the commandline nxmls (our local front-end to onsgmls) does not want the protocol identifier file: at all, regardless of how many slashes are specified.
- Files can be fixed rapidly and in bulk by handing them to the commandline routine fix_oXygen_SystemLiteral.perl. This program changes each file specified on the commandline and changes the SYSTEM literal stirng by stripping off the file:. Note that it does no XML parsing, and so may ruin a DOCTYPE declaration that is in an <eg> or <egXML> or inside some other comment, processing instruction, or CDATA section.

Technical Specification

<slide>
Content of slide to be displayed during a class
Roughly the equivalent of a <div type="slide">, this element contains the TEI source to a single graphic slide.

The content model is similar to a <div>, but only has component children (i.e., no <div> or <divGen> children).

<lectureNote>
Notes for the instructor
Roughly the equivalent of a <div type="lectureNote">, this element contains the TEI notes that are assiciated with its sibling <slide> element, which are for the presenter to use during a talk, but are not intended for the students (nor, however, are they hidden from the students).
﻿

The content model is the same as <div>.

<section>
Contains a single section of a presentation; typically a single slide's worth.

<handoutNote>
The portion of the notes to be handed out to students associated with this slide
Roughly the equivalent of a <div type="handoutNote">, this element contains the TEI source to a section of the student handout associated with the sibling <slide> or <lectureNote>.

The content model is the same as <div>.

<body>
presentation
slide show presentation
Equivalent to the TEI <body> element, contains a single (theorhetically) coherent slide presentation or lecture, consisting primarily of one or more <section>s or <sectionGrp>s.
ERROR: there are 'section' elements that have 'slide' as their second child, but others that have 'lectureNote' as their second child; should be consistent.

<eg>

@type
marks the example as being valid, well-formed, or ill-formed
"valid"
the example is valid with respect to the schema being discussed
May also be used to indicate that an example in a non-XML language is both syntactically and semantically correct.
"well-formed"
the example is well-formed XML, but no claim is made as to validity
"invalid"
the example is well-formed, but is invalid with respect to the schema being discussed
May also be used to indicate that an example in a non-XML language is syntactically valid but semantically incorrect, e.g. code that compiles but produces run-time errors.
"ill-formed"
the example is not well-formed (and therefore is not technically XML)
May also be used to indicate that an example in a non-XML language is syntactically incorrect, e.g. code that will produce compiler errors.

The YAPS <eg> element permits <hi> children elements to facilitate presentational distinction of items of interest.

<egXML>

@type
marks the example as being valid, well-formed, or ill-formed
"valid"
the example is valid with respect to the schema being discussed
"well-formed"
the example is well-formed XML, but no claim is made as to validity
"invalid"
the example is well-formed, but is invalid with respect to the schema being discussed

<pubPlace>

The first <pubPlace> child of the <pubicationStmt> of the main TEI header (i.e., /TEI/teiHeader/fileDesc/publicationStmt/pubPlace[1] should be the name of the venue at which the talk, workshop, lecture, or presentation was delivered.

<revisionDesc>

The content model is more restrictive than vanilla TEI, in that it does not permit <list>.

<list>

@type
Describes the form of the list. The values and their explanations are copied from the current copy of Sebastian's stylesheet core.xsl. Those that the yapsOut.xslt stylesheet knows about are emphasized; that stylesheet takes "unordered" as the default.
unordered
"bibl"
<item>s are processed in mode 'bibl'
"catalogue"
A gloss list is created, inside a paragraph
"gloss"
A gloss list is created, expecting alternate <label> and <item> elements
"glosstable"
<label> and <item> pairs are laid out in a two-column table
"inline"
A comma-separate inline list
"runin"
An inline list with bullets between items
"unordered"
A simple unordered list
"ordered"
A simple ordered list
"vallist"
(Identical to glosstable)

The content model has been changed mostly for technical reasons: because there is no model.divWrapper.bottom, the last portion of the content model gets boiled down to model.global**, which is invalid. Since we'll never want in <lb> (which is the only memeber of model.global) as the last child of a <list> anyway, we've just removed that portion of the content model.

Furthermore, since we have removed <head> from model.divWrapper, we need to explicitly refer to <head> near the top of <list>; but in fact, we don't want the other members of model.divWrapper here, so we juat replace a reference to that class with a reference to <head>.

<abbr>
@type

<title>
@type
classifies the title according to a limited typology.
"sub"
subtitle, title of part

Any <title> for which a @type is not specified is considered a "main" title.

We can add more types as needed.

<head>
@type
categorizes the heading as one of a very few catagories our stylesheet understands.
"sub"
subheading

Any <head> for which a @type is not specified is considered a "main" heading.

We can add more types as needed.

<note>
@place
suggested place to put the note on output
Value list copied from Sebastian's core.xsl stylesheet.
unspecified
"foot"
"end"
"display"
"inline"

<gloss>
@target
@cRef

The TEI @target and @cRef attributes are not currently used in YAPS.

<ptr>
@target
specifies the destination of the pointer, a single relative URI
#\i\c* ERROR: target= of does not point to anything. Unlike with a vanilla TEI <ptr>, our @target must be single barename relative URI, i.e. something that looks like "#duck".

We hope to remove the restriction on only a single barename relative URI in the future. I.e. fix the stylesheet so that multiple barenames can be processed.

It is conceivable that the restriction that the URI be a relative barename may also be removed at some point in the future, but we are much less confident of that.

@cRef

<ptr target="#here"/>
    <ptr target="#d17_03"/>

The TEI @cRef attribute is not available in this schema.

<ref>
@target
specifies the destination of the reference by supplying one or more URI References
One or more syntactically valid URI references, separated by white space. Because whitespace is used to separate URIs, no whitespace is permitted inside a single URI. If a whitespace character is required in a URI, it should be escaped with the normal mechanism, e.g. TEI%20Consortium.

Currently the main stylesheet we use to process YAPS documents does not know how to process more than one URI per @target attribute. Furthermore, when generating slides, it will generate incorrect links for bare name relative URI references (e.g. "#Nancy").

@cRef

The @cRef attribute is not available in this schema.

<term>
@cRef

This element is used to supply the form under which an index entry is to be made for the location of a parent <index> element.

In formal terminological work, there is frequently discussion over whether terms must be atomic or may include multi-word lexical items, symbolic designations, or phraseological units. The <term> element may be used to mark any of these. No position is taken on the philosophical issue of what a term can be; the looser definition simply allows the <term> element to be used by practitioners of any persuasion.

The TEI @cRef attribute is not available in this schema. Currently the main stylesheets we use for this language do not process the @target attribute intelligently.

<text>

Content model has been altered for purely technical reasons. Because we have a member of model.global but no <front> nor <back>, their portions of the content model boiled down to present.model.global*?, which is invalid. Thus we've just removed the <front> and <back> portions of the content model.

<sectionGrp>
section group
Groups together 2 or more <section>s under a single heading.

att.datable

att.divLike

att.declarable

<biblItem>

<sourceDesc>

att.declaring

<div>

att.editLike

<date>

model.pLike.front

<argument>

<epigraph>

model.titlepagePart

<figure>

<graphic>

att.identified

att.interpLike

att.measured

att.measurement

att.segLike

att.spanning

att.timed

model.blockLike

model.complexVal

model.catDescPart

model.divWrapper.bottom

model.editorialDeclPart

model.encodingPart

model.entryParts.top

model.featureVal

model.frontPart.drama

model.frontPart

model.gLike

model.global.edit

model.global.meta

model.glossLike

model.headerPart

model.lLike

model.lPart

model.measureLike

model.noteLike

model.oddDecl

model.oddRef

model.pPart.msdesc

model.personPart

model.profileDescPart

model.segLike

model.singleVal

model.sourceDescPart

model.stageLike

<add>

<altIdent>

<analytic>

<bibl>

<biblFull>

<biblStruct>

<binaryObject>

<cb>

<corr>

<del>

<desc>

<distinct>

<equiv>

<gap>

<imprint>

<index>

<l>

<lg>

<listBibl>

<measure>

<milestone>

<monogr>

<orig>

<pb>

<reg>

<series>

<sic>

<sp>

<speaker>

<stage>

<teiCorpus>

<unclear>

<broadcast>

<catDesc>

<catRef>

<category>

<classCode>

<classDecl>

<correction>

<creation>

<cRefPattern>

<editorialDecl>

<encodingDesc>

<equipment>

<extent>

<fragmentPattern>

<fsdDecl>

<hyphenation>

<interpretation>

<keywords>

<language>

<langUsage>

<metDecl>

<metSym>

<normalization>

<quotation>

<profileDesc>

<recording>

<recordingStmt>

<refsDecl>

<samplingDecl>

<scriptStmt>

<segmentation>

<seriesStmt>

<state>

<stdVals>

<taxonomy>

<textClass>

<variantEncoding>

<link>

<linkGrp>

<ab>

<anchor>

<seg>

<when>

<timeline>

<join>

<joinGrp>

<alt>

<altGrp>

<back>

<byline>

<closer>

<dateline>

<div0>

<div1>

<div2>

<div3>

<div4>

<div5>

<div6>

<div7>

<docAuthor>

<docDate>

<docEdition>

<docImprint>

<docTitle>

<floatingText>

<front>

<group>

<imprimatur>

<opener>

<salute>

<signed>

<titlePage>

<titlePart>

<trailer>

<attDef>

<attList>

<attRef>

<classSpec>

<classes>

<content>

<datatype>

<defaultVal>

<elementSpec>

<listRef>

<macroSpec>

<memberOf>

<moduleRef>

<moduleSpec>

<remarks>

<schemaSpec>

<specDesc>

<specGrp>

<specGrpRef>

<specList>

<stringVal>

<valDesc>

<valItem>

<valList>

att.global.linking
@corresp
@synch
@sameAs
@copyOf
copy of
points to an element of which the current element is a copy.
#\i\c* WARNING: if an element has copyOf=, it really shouldn't have (textual) content. ERROR: copyOf= of does not point to anything. WARNING: copyOf= should point to an element of same type. Unlike with a vanilla TEI @copyOf, ours must be single barename relative URI, i.e. something that looks like "#duck".

Any content of the current element should be ignored. Its true content is that of the element being pointed at.

@next
@prev
@exclude
@select

att.global
@rend
indicates how the element in question should be styled on output.
If the value is of the form css(…), then the string within the parens is passed through to the HTML as a @style attribute. If the value is of the form class(…), then the string within the parens (which should be a single token) as passed through to the HTML as a @class attribute.
@xml:base

anyTEI
teix:TEI xml:id xml:lang