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 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.

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.

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.

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:

insert the Mac OS X 10.6 (or similar) DVD from which you installed your system

open the Optional Installs folder

open the Xcode.mpkg package file

read license agreements and click Continue as needed

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.

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.

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:

roma will run slightly faster,
and

you will have a local copy of the bleeding edge
version of the TEI Guidelines on your hard drive, for easy
reference.

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.

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.

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.

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.