Roma CLI Instructions

These instructions, initially prepared by Trevor Munoz and Syd Bauman, are for installing roma to run from the command line. They are written for Mac OS X, but probably apply to most flavors of *nix operating systems as well. (However, if you have a Debian-based GNU/Linux system, you probably do better to use the TEI Debian packages.)

These instructions install the bleeding edge development version of the TEI Guidelines and stylesheets into your /usr/local/ directory tree. The (perhaps false) presumption is that you can use the Roma front-end (e.g., at the main TEI server or on Brown’s duplicate) to build customizations based on the released version, and that if you want to install the released version, you will want to install it into your /usr/ directory tree.

Dependencies

The following software packages need to be installed on your system in order for roma to work.

There are two more that are needed, but are not in the list above because the are already included in Mac OS X: libxml2 and libxslt. If you are using Mac OS X 10.6 you should already have these. If not, you may need to install them. To test to see if you already have libxml2 on your system, enter xmllint --version at the command prompt. If you do not get an error saying ‘command not found’ then libxml2 is already on your system. To test for libxslt, enter xsltproc --version at the command prompt.

If you already use a package management system like Fink, MacPorts, or pkgsrc, you may well find they have packages for some or all of these needed utilities. If not, install them on your own or follow the directions below.

saxon

The following instructions presume you are interested in Saxon Home Edition, the open source (and free as in beer) implementation.

Download the SaxonHE .zip file from Saxonica by clicking on “Download for Java (X.Y Mbytes)”. Some web browsers automatically unzip the download file for you, others do not. Here I will presume your browser did not automatically unzip the .zip file, that it is in your ~/Downloads/ directory, and that it is called saxonhe9-3-0-5j.zip. Two caveats: 1), the version number is likely to be different by the time you read this, and 2) it appears that the built-in Mac OS X unzipper (/System/Library/CoreServices/Archive Utility.app) will (by default?) “keep expanding” a .zip file, which in the case of a ZIPped .jar file (like Saxon) will result in an error. So either ensure that “Keep expanding if possible” is not checked in the Archive Utility prefernces, or don’t use that particular program to unzip.

In a shell session (e.g., by running /Applications/Utilities/Terminal) issue the following commands.

cd ~/Downloads/
unzip saxonhe9-3-0-5j.zip                      # browser may have already done
sudo mkdir -p /usr/local/bin/
cd /usr/local/bin/
sudo mv ~/Downloads/saxon9he.jar ./

Now, using any text editor (e.g., Emacs, oXygen, BBEdit, TextWrangler, Smultron; but not a word processor like MS Word, OpenOffice.org, or even TextEdit), create a new file called saxon, that reads as follows (filling in the bold fields with appropriate values):

#! /bin/bash
# front end to saxon.jar (for use by roma2)
# this file was copied from URL_of_this_page on date 
java -jar /usr/local/bin/saxon.jar $*

Save this file to your Desktop folder, being sure that there is no file extension (i.e., saxon not saxon.txt or saxon.sh; be warned that some applications try pretty hard to make sure you have an extension).

Now from the shell session issue:

sudo chmod +x ~/Desktop/saxon
sudo mv ~/Desktop/saxon /usr/local/bin/

to make the new script executable and move it to a reasonable place (both so that it will be easy to execute and so that it doesn’t clutter up your desktop.)

You can test that saxon is installed and works by simply entering saxon at your commandline. You should get the error message “No source file name” followed by a screen-full of usage information.

trang

From the download page, download the newest trang-version.zip by clicking on the link next to “Trang version version packaged for use with JRE (includes binary, source and documentation)” (typically this is the top of the table). Here I will presume it is in your ~/Downloads/ directory, that your browser has not unzipped it for you, and that it is called trang-20091111.zip.

In a shell session (e.g., by running /Applications/Utilities/Terminal) issue the following commands.

cd ~/Downloads/                       # you can skip these two steps if
unzip trang-20091111.zip              # your browser already unzipped
cd /usr/local/bin/
sudo mv ~/Downloads/trang-20091111 ./
sudo ln -s trang-20091111/trang.jar trang.jar

Now, using any text editor (e.g., Emacs, oXygen, BBEdit, TextWrangler, Smultron; but not a word processor like MS Word, OpenOffice.org, or even TextEdit), create a new file called trang, that reads something like the following (filling in the bold fields with appropriate values).

#! /bin/bash
# front end to trang (for use by roma2)
# this file was copied from URL_of_this_page on date 
java -jar /usr/local/bin/trang.jar $*

Save this file to your Desktop folder, being sure that there is no file extension (i.e., trang not trang.txt or trang.sh; be warned that some applications try pretty hard to make sure you have an extension).

Now from the shell session issue:

sudo chmod +x ~/Desktop/trang
sudo mv ~/Desktop/trang /usr/local/bin/

to make the new script executable and move it to a reasonable place (both so that it will be easy to execute and so that it doesn’t clutter up your desktop).

You can test that trang is installed and works by simply entering trang at your commandline. You should get the error message “fatal: at least two arguments are required” followed by some usage information.

jing

If you wish to install jing, the process should be almost exactly the same as that for trang. The only difference is that the jing.jar file is stored inside a bin/ directory.

From the download page, download the newest jing-version.zip by clicking on the link next to “Jing version version packaged for use with JRE (includes binary, source and documentation)” (typically this is the 2nd from the top of the table). Here I will presume it is in your ~/Downloads/ directory, that your browser has not unzipped it for you, and that it is called jing-20091111.zip.

In a shell session (e.g., by running /Applications/Utilities/Terminal) issue the following commands.

cd ~/Downloads/                       # you can skip these two steps if
unzip jing-20091111.zip               # your browser already unzipped
cd /usr/local/bin/
sudo mv ~/Downloads/jing-20091111 ./
sudo ln -s jing-20091111/bin/jing.jar jing.jar

Now, using any text editor (e.g., Emacs, oXygen, BBEdit, TextWrangler, Smultron; but not a word processor like MS Word, OpenOffice.org, or even TextEdit), create a new file called jing, that reads something like the following (filling in the bold fields with appropriate values).

#! /bin/bash
# front end to jing (for use by roma2)
# this file was copied from URL_of_this_page on date 
java -jar /usr/local/bin/jing.jar $*

Save this file to your Desktop folder, being sure that there is no file extension (i.e., jing not jing.txt or jing.sh; be warned that some applications try pretty hard to make sure you have an extension).

Now from the shell session issue:

sudo chmod +x ~/Desktop/jing
sudo mv ~/Desktop/jing /usr/local/bin/

to make the new script executable and move it to a reasonable place (both so that it will be easy to execute and so that it doesn’t clutter up your desktop).

You can test that jing is installed and works by simply entering jing at your commandline. You should get a version # and usage message.

make

The TEI uses a Unix Makefile for building P5. Thus the command used for building is make. Mac OS X 10.6 does not come with make pre-installed. There are a variety of ways to install a make command, including via a package management system or building from sources downloaded directly from the FSF website. By far the easiest method, however, is to install it via the Apple ‘developer tools’ installer. This has the advantage of being really easy to do, and installing some other software you might someday want (like gcc). However, it has the disadvantage of installing at least 1.7 GiB of stuff, where the one command we want is < 310 KiB. Sigh.

To install make via the Apple installer:

  1. insert the Mac OS X 10.6 (or similar) DVD from which you installed your system
  2. open the Optional Installs folder
  3. open the Xcode.mpkg package file
  4. read license agreements and click Continue as needed
  5. optional: to use less space, uncheck all except “Essentials” (which you can’t uncheck) and “UNIX Dev Support” at the “Custom Install” step; that is, you don’t need “System Tools”, “Documentation”, or “Mac OS X 10.4 Support”

Get the TEI Source

This is not as simple as it sounds (in this environment — it is very simple in Debian GNU/Linux or a derivative thereof like Ubuntu). There are multiple bits to download and put in the appropriate places.

The Guidelines

Next, download a copy of the actual source of TEI P5 (the ODD files, plural; the hemispherical base at the bottom of the graphic you’ve all seen). To do this issue the following from your commandline.

sudo mkdir -p /usr/local/share/xml/tei/
cd /usr/local/share/xml/tei/
sudo svn co https://tei.svn.sourceforge.net/svnroot/tei/trunk/P5 odd/

That last command may take a few minutes: you are downloading > 1300 files (~ 33 MiB) from Sourceforge.

You can visit the webpage at the TEI Consortium with information on using the Sourceforge repository: http://www.tei-c.org/Guidelines/P5/get.xml.

The Stylesheets

You also need a copy of ‘the stylesheets’, the guts of roma. To obtain these issue the following from your commandline.

cd /usr/local/share/xml/tei/
sudo svn co https://tei.svn.sourceforge.net/svnroot/tei/trunk/Stylesheets stylesheet/

Roma itself

You also need the shell script that makes use of the stylesheets. We’ll get that by downloading the TEI Roma/ directory. Most of this directory is for supporting Roma the web interface, but it includes the program we need, namely roma2. So to get it, issue the following commands.

cd /usr/local/share/
sudo svn co https://tei.svn.sourceforge.net/svnroot/tei/trunk/Roma tei-roma/
cd /usr/local/share/tei-roma/
sudo make LOCATION=/usr/local install

Build TEI P5 (optional)

In order to generate customizations, roma needs to read the source to the TEI Guidelines, which you already obtained, above. There is nothing more that you need to do. However, if you ‘build’ P5 from the source, there are two advantages:

To just speed up roma a bit, all we need to do is generate p5subset.xml, which can be done with just the following commands:

cd /usr/local/share/xml/tei/odd/
sudo make oddschema

Note that this command will likely fail with “ERROR: stylesheet location /usr/share/xml/tei/stylesheet/ is not accessible.”. This is OK. All we needed was the first part, which generated p5subset.xml.

However, it would be nice to actually have a copy of the bleeding edge development version of the TEI Guidelines to read and browse, given that your customization will be built against it. In order to do this issue the following commands.

cd /usr/local/share/xml/tei/odd/
sudo make XSL=/usr/local/share/xml/tei/stylesheet html-web

Note that this will probably produce a lot of output messages on your terminal screen. However, if all’s well when it’s done, you can point your browser to file:///usr/local/share/xml/tei/odd/Guidelines-web/en/html/index-toc.html and read the bleeding edge Guidelines whenever you want, with or without an internet connection!

Customize!

The program that processes TEI customizations is a script called roma2. This command is somewhat complicated, but once you’ve figured out how to use it, you can save that in another script (which we’ll call roma, see below).

To use the roma command from your commandline interface first switch to the directory where you want the output to go (which may or may not be the same as the directory with the intput file). using the cd command, e.g. cd ~/Desktop/.

Then issue one of the following two roma2 commands, replacing the bold text (near the end) with the correct path on your system. The first version of the roma2 command is for those who successfully generated the p5subset.xml file in the Build TEI P5 step, above. The second is for those who did not. It is mostly the same command, and should generate the same output, but should take a few seconds longer.

So, if you have p5subset.xml, issue:

roma2 --xsl=/usr/local/share/xml/tei/stylesheet --localsource=/usr/local/share/xml/tei/odd/p5subset.xml --dochtml --nodtd --noxsd --isoschematron /path/to/input.odd ./

If you do not have p5subset.xml, issue:

roma2 --xsl=/usr/local/share/xml/tei/stylesheet --localsource=/usr/local/share/xml/tei/odd/Source/Guidelines/en/guidelines-en.xml --dochtml --nodtd --noxsd --isoschematron /path/to/input.odd ./

In either case, make sure to change the path of the input file (in bold near the end of the command) to point to your ODD file.

This command is complicated enough that it deserves some explanation. But (at least for the moment) I’m not providing it here. Rather, read the help documentation for roma2 by issuing the following.

roma2 --help

Simplifying roma

Once you have copied-and-pasted that long commandline to your shell (i.e., to your commandline interface), you need not copy it again. You can re-issue the command in your shell (typically typing the up-arrow key will bring back the previous commandline and even allow you to edit it before entering it again). But if you quit your shell environment this may not work, and who wants to find that command and copy-and-paste it (and edit the input path) over and over? So in order to avoid needing to remember or copy-and-paste that long command, it is useful to create a simple shell script front-end. This is especially useful if you enter (or plan to enter) the roma2 command frequently with the same switches.

To do this, once again create a new text document with any text editor (e.g., Emacs, oXygen, BBEdit, TextWrangler; but not a word processor like MS Word, OpenOffice.org, or even TextEdit). Copy-and-paste the following lines of code into it.

#! /bin/bash
# local front-end to roma
roma2 --xsl=/usr/local/share/xml/tei/stylesheet \
      --localsource=/usr/local/sahre/tei/odd/Source/Guidelines/en/guidelines-en.xml \
      --dochtml --nodtd --noxsd --isoschematron \
      $* ./

If you successfully generated a p5subset.xml file previously, you should use it instead for mildly improved performance. To do so use “p5subset.xml” instead of “Source/Guidelines/en/guidelines-en.xml”. You should also replace any of the switches on the 2nd to last line with more appropriate values as needed. E.g., if you need DTD output, remove the “--nodtd” switch.

Now save this file to your Desktop folder, being sure that there is no file extension (i.e., roma not roma.txt or roma.sh; be warned that some applications try pretty hard to make sure you have an extension).

Now from the shell session issue:

sudo chmod +x ~/Desktop/roma
sudo mv ~/Desktop/roma /usr/local/bin/

to make the new script executable and move it to a reasonable place (both so that it will be easy to execute and so that it doesn’t clutter up your desktop.)

You should now be able to run roma from your commandline interface using two simple commands:

cd /path/to/desired/output/directory/
roma /path/to/input.odd

In the (common) case that the desired output directory is the same as the directory that contains the input ODD file, the /path/to/ the input.odd file is nil. So the command you end up entering over and over again as you refine your ODD is just roma input.odd. In many commandline environments the last command that was entered at the commandline can be recovered by just typing the ↑ (up-cursor) key. Thus the sequence to re-issue the command is often only 2 keystrokes: ↑ and ENTER.

Voilà

That’s it. In short order, roma should generate schema files and documentation for your TEI customization.