Background

XTF is an XML publication framework. For our purposes, there are basically two processes we need to understand in order to set it up and work with it:

• It indexes our XML documents, using the “textIndexer”. This means that it reads all the XML documents we offer it, and indexes them for efficient searching and processing. When we start XTF for the first time, we need to run the textIndexer to index our texts, and if we add or remove any texts from the collection we need to run the textIndexer again to refresh the index and reflect these changes.
• It publishes data for us to read and query via a web browser. To support this activity, it includes a web serverlet named “tomcat” that is built into XTF. In order to see our data in a web browser, we need to launch tomcat so that the data from XTF can be served up to the browser. When we make changes to the indexed data, we need to shut down tomcat and relaunch it.

Detailed step-by-step instructions are given below for getting XTF up and running. In places where the instructions say “issue the command...” this just means you should type the given command into your terminal window (which will be launched when you start up XTF).

We have provided a test data set that includes 100 TEI-encoded articles from the DHQ journal. You should feel free to use your own data instead, but XTF has a few quirks you should be aware of in preparing that data:

• XTF requires that your documents include a <titlePage> element
• XTF requires that all of your <div> elements have @xml:id attributes

Basic XTF Instructions

1. Get the appropriate XTF package
   • if you’re in the workshop, you can copy either XTF_exercise_Windows/ or XTF_exercise_Mac_Linux.tgz as appropriate from the Transforming_and_Publishing_TEI_day_3-selected/ directory on a USB stick; for Mac or GNU/Linux you’ll need to expand the compressed archive file (typically by double-clicking it)
   • if you’re not at the workshop, you can download the package for Mac/Linux or Windows
2. Launch XTF by opening cmdPrompt.command (Mac or Linux) or cmdPrompt.bat (Windows). If you are on a Mac and you receive an error message saying "cmdPrompt.command can't be opened because it is from an unidentified developer", control-click on the cmdPrompt.command icon and then choose Open.
3. TEMPORARY: for Mac or GNU/Linux, fix the permissions by issueing the command chmod a+x textIndexer tomcat/bin/* tomcat/webapps/xtf/bin/textIndexer
4. Index the XML data it contains by entering either

   ./textIndexer -index default   (Mac or Linux)

   or

   textIndexer -index default   (Windows)

   This makes XTF aware of the XML files that are in its data folder, XTF_exercise/tomcat/webapps/xtf/data/ (we’ve preloaded this with 100 articles from Digital Humanities Quarterly). You’ll know the indexing process is done when the command window says “Indexing complete.”
5. Launch tomcat by opening tomcat.command (Mac or Linux) or tomcat.bat (Windows). You’ll know this process is complete when the tomcat window says “INFO: server startup in NUM ms”
6. In a web browser, visit the address:

   http://localhost:8080/xtf/search

   If you get an XTF browser interface, things are going well!
7. Try a search (hint: the texts in this collection are from a digital humanities journal)
8. To replace the default data with your own data:
   1. go to XTF_exercise/tomcat/webapps/xtf/data/. You’ll see a list of files with names like 000001.xml (these are DHQ articles).
   2. Delete these and replace them with your own XML files.
   3. Next, shut down tomcat by typing control-c (??)
   4. Then run the indexer again to reindex the data: in the command window type ./textIndexer -index default
   5. Restart tomcat (see step 5 above) (??)
   6. Reload the XTF browser: http://localhost:8080/xtf/search

Troubleshooting

• if you’ve added new data, but it’s not showing up in XTF, did you remember to run the indexer after adding the new data (step 3 or 8b above)?
• if you can’t get to the localhost page at http://localhost:8080/xtf/search, try restarting tomcat (step 4 above)

Tutorials and documentation

A full XTF tutorial with step-by-step exercises is available at http://xtf.cdlib.org/getting-started-tutorials/. Note that all the filepaths mentioned in the tutorial start at XTF_HOME, which is equivalent to the XTF_exercise_Windows/tomcat/webapps/xtf/ directory in our self-contained XTF Workshop installation.

Full XTF documentation (aimed at a fairly advanced audience) is available at http://xtf.cdlib.org/documentation/ (same proviso as above).