Scandinavian-Canadian Studies

If you look at Rudling 2, 20, you'll see an author with a pseudonym. In the biblio, the pseudonym is handled like this:

<biblStruct>
                      <monogr>
                        <author><name reg="Gunnarson, Karl: see Schulze, Karl Gunnar">Karl Gunnarson see Schulze, Karl Gunnar</name></author>
                        <title></title>
                        <imprint></imprint>
                      </monogr>
                    </biblStruct>

And the main entry looks like this:

                  <biblStruct>
                    <monogr>
                      <author><name reg="Schultze, Karl Gunnar (pseud. Karl Gunnarson)">Karl Gunnar Schultze (pseud. Karl Gunnarson)</name></author>
                      <title level="m">På Kanadas prärier</title>
                      <imprint>
                        <pubPlace>Stockholm</pubPlace>
                        <publisher>Folket i Bilds Förlag</publisher>
                        <date value="1939">1939</date>
                      </imprint>
                    </monogr>
                  </biblStruct> 

When we encounter quotation marks or italics in a text, we generally have to make a decision about the reason they've been used before we can mark them up. These are the most common tags, and what they're used for:

• <emph>: Used for simple emphasis, as with the word reason above. These usually render into italics.
• <mentioned>: Used when a word is mentioned rather than used -- in other words, the word itself is the topic, rather than being used to refer to something. The word reason in this sentence is an example (and in the bullet above).
• <soCalled>: Used for "scare quotes", or situations in which the author is maintaining an ironic distance from the word or phrase. The phrase scare quotes above is an example of this: I've put it in quotes, suggesting that it's somehow not a formal term, or is only semi-serious. Renders into quotes.
• <term>: Used for technical terms which are highlighted in some way (usually italics, but sometimes quotes). Renders into italics.
• <hi rend="foreign">: Used for a word or phrase taken from another language which has been italicized for that reason in the original. Ceteris paribus this will be rendered into italics. Note that there is also a <foreign> tag, but this is used only when font changes are required (for instance when including Japanese or Greek text which requires a specific font).
• <hi rend="italic">: Used when all else fails (i.e. you have no idea why the italics are there, but you need to render them.

These tags are distinct from ordinary quotations, of course, which are dealt with in another post. Also, note that inside quotations, we may find it difficult or undesirable to speculate about why the quoted source uses italics or quotation marks, so we may simply leave the original quotation marks, or use <hi rend="italic">, to avoid making a choice. In the case of the text of our own authors, we should always be able to tell why such highlighting is used, and if we can't, we can ask, or the editor may decide it should be removed.

Below is a list of various common types of bibliography item, and how they're captured in <biblStruct> elements in the back matter of the document. As always, actual markup practices represent a compromise between the desire to mark things up accurately and usefully, and the requirement to produce rendered output which conforms with the expectations of authors and editors. The former imposes consistency, but the latter often requires that we violate or override that consistency because of personal style preferences. Therefore you will find kludges in the markup of some items, especially unusual items.

A common fallback where a kludge is required is to use the <note> element right at the end of <biblStruct> (as its last child). The entire contents of such a <note> tag are rendered out at the end of the entry.

Within a single bibliography list, items are ordered by hand (by the original author and editor); the original order is preserved in the XML, and no automated sorting takes place during rendering. It has proved impractical to sort biblio items in XQuery or XSLT, because they are so idiosyncratic.

• Book:

        <biblStruct>
        <monogr>
        <author><name reg="Berggren, Henrik">Henrik Berggren</name></author>
        <author><name reg="Trägårdh, Lars">Lars Trägårdh</name></author>
        <title level="m">Är svensken människa? Gemenskap och oberoende i det moderna Sverige</title>
        <imprint>
        <pubPlace>Stockholm</pubPlace>
        <publisher>Nordstedts</publisher>
        <date value="2006">2006</date>
        </imprint>
        </monogr>
        </biblStruct>
      

  Note that the regularized form of the name (last, first) must always be supplied along with the normal form, so that the rendering code can use whichever is appropriate in the circumstances (so the reg form is used for the first author, and the normal form for the second, in this case). In the case of "et al.", just add the phrase "et al." to the end of the last author's (or editor's) name inside the tag (the actual name is recoverable mechanically from the @reg attribute, so this kludge is not too destructive).
  
  The date element has both @value (a constrained value as yyyy[-mm[-dd]]), as well as textual content; normally, they're identical, but in a case where the same author has multiple publications in the same year, the text content is used to show "1999a", "1999b" etc. The text content will be used when rendering, but the @value is available for mechanical processing if this is required in the future.
• Book with a translator:

                    <biblStruct>
                      <monogr>
                        <author><name reg="Nietzsche, Friedrich">Friedrich Nietzsche</name></author>
                        <respStmt>
                          <resp>Trans.</resp>
                          <name reg="Smith, Douglas">Douglas Smith</name>
                        </respStmt>
                        <title level="m">The Birth of the Tragedy</title>
                        <imprint>
                          <date value="2000">2000</date>
                          <pubPlace>Oxford</pubPlace>
                          <publisher>Oxford University Press</publisher>
                        </imprint>
                      </monogr>
                    </biblStruct>
  

  Note that the <respStmt> tag can be used for other similar purposes (illustrator, etc.). If there are multiple translators, use multiple name tags in the same <respStmt>.
• Book in a series:

                    <biblStruct>
                      <analytic>
                        <author><name reg="Sundholm, John">John Sundholm</name></author>
                        <title level="a">Juha</title>
                      </analytic>
                      <monogr>
                        <title level="m">The Cinema of Scandinavia</title>
                        <title level="s">24 Frames</title>
                        <editor><name reg="Soila, Tytti">Tytti Soila</name></editor>
                        <imprint>   
                          <publisher>Wallflower Press</publisher>
                          <pubPlace>London</pubPlace>
                          <biblScope type="pages">214-222</biblScope>
                          <date value="2005">2005</date>
                        </imprint>
                      </monogr>
                    </biblStruct>
  

• Chapter in a book:

        <biblStruct>
        <analytic>
        <author><name reg="Bibby, Michael">Michael Bibby</name></author>
        <title level="a">Atrocity Exhibitions: Joy Division, Factory Records, and Goth</title>
        </analytic>
        <monogr>
        <editor><name reg="Goodlad, Lauren M.E.">Lauren M.E. Goodlad</name></editor>
        <editor><name reg="Bibby, Michael">Michael Bibby</name></editor>
        <title level="m">Goth: Undead Subculture</title>
        <imprint>
        <publisher>Duke University Press</publisher>
        <pubPlace>Durham, NC</pubPlace>
        <date value="2007">2007</date>
        </imprint>
        </monogr>
        </biblStruct>
      

  Two things to note: titles are at two levels ("a" for the chapter -- analytical -- and "m" for the containing book -- monograph); and periods are not supplied at the end of titles. These will be supplied automatically during rendering, if they are required in the output. Other types of punctuation such as question marks should be supplied at the end of titles.
• Journal article:

        <biblStruct>
          <analytic>
            <author><name reg="Knutsson, Johannes">Johannes Knutsson</name></author>
            <author><name reg="Strype, Jon">Jon Strype</name></author>
            <title level="a">Police Use of Firearms in Norway and Sweden: The Signficance of Gun Availability</title>
          </analytic>
          <monogr>
            <title level="j">Policing &amp; Society</title>
            <imprint>   
              <biblScope type="vol">13 (4)</biblScope>
              <biblScope type="pages">429-39</biblScope>
              <date value="2003">2003</date>
            </imprint>
          </monogr>
        </biblStruct>
      

  Note the inclusion of the page numbers. Page numbers for book chapters (above) can be included in the same way.
• Newspaper article:

        <biblStruct>
        <analytic>
        <author><name reg="Felperin, Leslie">Leslie Felperin</name></author>
        <title level="a">Joachim Trier: 10 Directors to Watch</title>
        </analytic>
        <monogr>
        <title level="j">Variety</title>
        <imprint>
        <biblScope type="vol">17 January</biblScope>
        <date value="2007">2007</date>
        </imprint>
        </monogr>
        <note><xptr to="http://www.variety.com/article/VR1117957586.html?categoryid=13&cs=1&query=joachim+triert" crdate="2009-12-31"/></note>
        </biblStruct>
      

  Note: this also shows the use of the <note> element with an <xptr> to give the URL of the article online.
• Online article:

                    <biblStruct>
                      <analytic>
                        <author><name reg="Harsin, Jason">Jason Harsin</name></author>
                        <title level="a">Von Trier’s Brechtian Gamble</title>
                      </analytic>
                      <monogr>
                        <title level="j">Bright Lights Film Journal</title>
                        <imprint>
                          <biblScope type="vol">51</biblScope>
                          <date value="2006">2006</date>
                        </imprint>
                      </monogr>
                      <note><xptr to="http://www.brightlightsfilm.com/51/manderlay.htm" crdate="2009-09-23"/>.</note>
                    </biblStruct>
      

• Monograph listed by name rather than author:

        <biblStruct>
          <monogr>
            <title level="m"><name>Norsk film i møte med kinopublikum: Analyse av kinobesøket på norske filmer 2003-2006</name></title>
            <imprint>
              <date value="2007">2007</date>
              <pubPlace>Oslo</pubPlace>
              <publisher>Norwegian Film Institute</publisher>
            </imprint>
          </monogr>
        </biblStruct>
      

  Note: there is no <author> element, but the <title> element contains a <name> element, which tells the processing system that this is the name which should lead off the entry.
• Cinema film:

          <biblStruct>
            <monogr>
              <author><name reg="Trier, Lars von">Lars von Trier</name></author>
              <title level="m">Riget <hi rend="normal">(part I)</hi></title>
              <imprint>
                <date value="1994">1994</date>
                <pubPlace>Copenhagen</pubPlace>
                <publisher>Zentropa</publisher>
              </imprint>
            </monogr>
          </biblStruct>
        

No date

If there is no known or available date for an item, simply do this:

<date>n.d</date>

Overriding styles

Sometimes, the requirements of rendering are in conflict with the semantics of TEI markup, and some nudging is required in order to get the output you want. An example would be a monograph title which should be in italics, but for some reason, part of it needs to be rendered in normal style. This can be achieved using the following tag:

      <hi rend="normal">This text will be undecorated, non-italic, and non-bold.</hi>
    

Other tags

• Web links are created with <xptr> tags:

  <xptr to="http://scancan.net/"/>
  

  The URL will be used to create the link (in PDF and XHTML output) and will serve as the clickable text as well. During PDF rendering, invisible spaces are inserted into long URLs rendered as clickable links, so that the rendering engine can create soft linebreaks when wrapping is required.
• Footnotes are included immediately inline where the footnote number should appear. They will be automatically rendered as endnotes or popups during the output process:

  This sentence ends with a footnote.<note>This is the footnote.</note>
  

• Titles are handled everywhere with the <title> tag, using the @level attribute to designate what kind of title they are (m = monograph or standalone, a = analytic or component of a larger work, s = series, u = unpublished, j = journal or periodical). These attributes will automatically get you the formatting you need; for instance, this will be italicized:
  

  <title level="m">Hedda Gabler</title>

  and this will acquire double quotes around it:
  

  <title level="a">Dover Beach</title>

  In the latter case, remember that you'll have to include any punctuation that needs to appear in the quotes inside the <title> tag. This is annoying but basically unavoidable (without lots of costly rendering processing).
• Glosses are handled using the <gloss> tag, which will generate square brackets during rendering.
• Titles with glosses need careful attention. There are two types. The first is where the gloss title is simply a translation of the original title:
  

  <title level="m">Hiroshima Mon Amour</title> <gloss>Hiroshima My Love</gloss>

  which will come out looking like this:
  Hiroshima Mon Amour [Hiroshima My Love]
  The second is where a work has been released in translation, and the gloss title is the title of the published translation:
  

  <title level="m">Ivo Caprino’s Flåklypa Grand Prix</title> <gloss><title level="m">Pinchcliffe Grand Prix</title></gloss>

  which will render like this:
  Ivo Caprino’s Flåklypa Grand Prix [Pinchcliffe Grand Prix]
• So-called (scare quotes): Anything which is in "scare quotes" (see Wikipedia for a definition) should be marked up with the <soCalled> tag, which generates the quotes automatically during rendering.
• mentioned (words mentioned rather than used): There is some inconsistency here in the editorial practice. This is an example of a word being mentioned rather than used:
  

  The Japanese word mizu means water.

  In this case, as in many others in the ScanCan documents, the word is italicized. The TEI tag <mentioned> is used here, and will result in italicized output. However, there are also many instances of a word being mentioned rather than used where the original writed supplied it in quotation marks rather than italicized, and the editor prefers to keep it that way in the output. Therefore these words must be marked up differently so that they appear in quotation marks. In most instances, it's possible to make a plausible case that the word is also being quoted from somewhere else, so it can be marked up using <cit><q>. This is not ideal, but it's a predictable outcome of the need to blend a real-world editorial policy, which is flexible and tends to honour a writer's idiosyncratic style rather than trying to impose a rigorous set of rules, and the more unforgiving categorization that markup demands.
• Images in the text: Images are inserted using a <figure> element, with <xref> pointing to the image file by name. The image files themselves are located in the /images/ directory inside the Cocoon site, and are named based on the filename of the XML document, with an appended underscore followed by the number of the figure. The XSLT takes care of building the link correctly. The caption is encoded in a <head> tag.
  

    <figure rend="ImageLink">
      <head>Genocide victims are loaded into the back of a truck in Andersson’s award-winning short film <title level="m">Härlig är Jorden</title> <gloss><title level="m">World of Glory</title></gloss> (1991). Photo courtesy of Studio24.
      </head>
      <p><xref>lindqvist_1_18_1.jpg</xref></p>
    </figure>
  

Minor quirks and idiosyncratic practices

• Ellipses are always done like this:

  <hi rend="Garamond">…</hi>
  

  The ellipsis is the real ellipsis character (u+2026), and the rend attribute invokes the use of the Garamond font (at least when rendering for PDF). The editor dislikes the spacing of the ellipsis character in the main Gentium font used for PDFs, so this character is rendered differently. A space is used both before and after the ellipsis.

Quotes are complicated in this project, because of the need to handle glossing of them. Below is a set of example markups, with explanations.

• Simple inline quote:

  <cit><q>This is the quotation that will be rendered inline.</q> <bibl>53</bibl></cit>
  

  Note that the quotation marks are not included in the text itself; these are supplied by the rendering. This enables us to standardize the appearance of quotes, and avoid errors with straight vs. smart quotes. Also, the <bibl> (page reference or whatever) doesn't require parentheses; these are supplied by the rendering engine. Any <bibl> element inside a <cit> element will acquire parentheses.
• Simple blockquote:

  <cit rend="block"><q>This is the quotation that will be rendered as a block.</q> <bibl>53</bibl></cit>
  

  As above, no parentheses required for the <bibl> content. Blockquotes like this are encoded inside the paragraph (<p>) in which they appear.
• Blockquote with gloss:

  <cit rend="block"><q>This is the quotation that will be rendered as a block.</q> <bibl>53</bibl></cit>
  
  <cit rend="block"><q><gloss>This is the gloss of the above quotation.</gloss></q> <bibl>65</bibl></cit>
  

  Note that the gloss may come from a published translation, in which case its <bibl> will reflect that source; or it may be supplied by the article author, in which case there may not be a <bibl> element in the second <cit>.
• Inline parenthetical reference:

  According to Bloggs, this novel is rubbish <cit><bibl>189</bibl></cit>.
  

  This is just like a normal inline quotation, but there's no quote. The parentheses will be supplied by the processing. (If this seems like overkill, it's because there's a long-term plan to link all such inline references to the bibliographical details at the end of the document. Someday this will be accomplished.)
• Inline quote with gloss:

  <cit><q><orig>Det er typisk norsk å være god</orig> <gloss>It is typically Norwegian to be good</gloss></q> <bibl>Brundtland</bibl></cit>
  

  This is like a normal quote, but the q tag is subdivided into <orig> and <gloss>; the former will be given quotation marks in the rendering, and the latter will get square brackets.
• Fragmented quotations: These occur when the quotation is separated from the reference info, and so they can't be contained by the same <cit> tag. Each needs its own <cit>:

  Bjørn Sørenssen suggests <cit><q>Wild and enthusiastic</q></cit> as a more accurate translation of the title <cit><bibl>235</bibl></cit>.
  

Overall document structure is probably best discovered simply by examining the existing files, but major markup features and practices are enumerated below.

<teiHeader> and <front>

• Documents are named for author and volume, with an additional integer in the middle which serves to differentiate two documents when the same author has two documents in the same volume. For instance: sayers_1_18.xml means "Sayers's first document in volume 18".
• The XML file name, minus extension, is also used as the @id attribute on the root <TEI.2> tag (<TEI.2 id="sayers_1_18">).
• The root element may also carry an @rend="proof_only" attribute. When this is present, the document will not show up in the main TOC of the site; instead it will appear on the "Proofing" page, where documents are made available to editors and authors for proofing before publication. When a document is deemed published or fit for publication, its @rend attribute can be removed, promoting it to the main TOC.
• The <front> element has <docTitle> element that looks like this:

  <docTitle n="Norwave: Norwegian Cinema 1997-2006">
      <titlePart type="Main">Norwave: Norwegian Cinema 1997-2006</titlePart>
      <titlePart type="Running">Norwave: Norwegian Cinema 1997-2006</titlePart>
  </docTitle>
  

  The @n attribute provides a markup-free version of the title, which can be used in processing without fear that it contains tags (whereas the other titles may contain markup). The main title is used on the first page of the article, and the running title obviously at the head of pages in the PDF/print version; this is often shorter than the main title, and must be created in consultation with the editor, and tested to make sure it will fit in the output.
• Following <docTitle> in <front>, we find:

   <docAuthor><name key="holmes_martin" reg="Holmes, Martin">Martin Holmes</name> has been hanging around the University of Victoria for nearly fifteen years, doing various menial jobs. E-mail: <xptr to="my@e.mail" type="email"/>. 
      </docAuthor>
  

  This is the "long bio" which shows up on the website when you look at the Contributors page, or in a printed volume on its Contributors page. Note the need to supply the name in regularized format, and also in the form of a key. Throughout the header, the same formulation is used for a name. This is repetitive, but it makes for easy processing whenever a name is retrieved.
• Finally, in front, we have a "short bio":

      <titlePart type="short_affil">Martin Holmes is a layabout at the University of Victoria.</titlePart>
  

  This is used at the bottom of the article title page (in the case of an article) or at the bottom of a review. NOTE: The format of this will differ in each case; for an article, it needs to be a full sentence, starting with the author's name, whereas for a review, it follows the author's name on the next line, and so it has to be a noun phrase. Look at existing markup for examples.

Structure of <body>

• The body is divided into <div0> elements, one for each major section. If there is only one section, there is only one <div0>.
• Each <div0> can have a single <head> tag at the top of it, containing a heading for the section.
• Content inside the <div0>tags, following any <head>, consists mainly of <p> (paragraph) tags.
• The first letter of the first <p> of the first <div0> is usually formatted as a large drop-capital in a fancy font for the print version. This is marked up thus:

   <p><hi rend="DropCap">A</hi>lthough its subtitle identifies it ...</p>
  

  Where the article starts with an inline quotation, both the opening quote and the first letter are included in the drop-cap tag. This means that the opening quotation cannot be marked up as a quote in the normal way, which is unfortunate; actual (smart) quotes are used in this situation. Here aesthetics trumps coding rigour.

Structure of <back>

The <back> element contains the bibliography (sometimes more than one, if they're divided into sections). The structure looks basically like this:

<back>
<div type="Bibliography">
<head>REFERENCES</head>
<listBibl>
  <biblStruct>...</biblStruct>
</listBibl>
</div>
</back>

The content of <biblStruct>s is complicated, and documented with lots of examples in its own blog posting.

I'm building a basic introduction to the ScanCan project for any programmer who might have to take over the project in the event that I'm "hit by a bus", or otherwise not available. This post will be built up steadily over time, as I document the app structure, markup practices etc.

Application structure

The application currently lives in the main Cocoon servlet on the "production" Tomcat on Lettuce. It shares that servlet with several other applications, but right now it's the most "live" and important. The XML data (articles and reviews) lives in a single collection in the db called "scancan".

DTDs/standards

This is a legacy project which still uses TEI P4 (even though it's in steady use, with new material being added every year). The DTD for the XML markup is tei_scancan.dtd; it was generated from the old TEI Pizza Chef tool without customizations.

Other standards used are XHTML 1.1 (for web output), CSS 2.1, JavaScript (no specific version, but probably nothing newer than 1.2), and XSL:FO in the production of PDFs. PDF production is done using XEP, and does make use of some XEP-specific features (for instance, to provide a useful TOC sidebar in the PDF file for a journal volume). This means the project as it stands is dependent on XEP.

Key pipelines and XSLT files

Future development