Alexandria: A Command-line Application for Digital Text Editing

GitHub Actions Project Status: Inactive – The project has reached a stable, usable state but is no longer being actively developed; support/maintenance will be provided as time allows.

What is it?

In short: Alexandria is a text repository system in which you can store and edit documents. It is the reference implementation of TAG (Text-as-Graph), a flexible graph data model for text. TAG and Alexandria are under active development at the Research & Development group of the Humanities Cluster.

You may wonder, why use Alexandria if you already have a text editing tool? Well, if you’d like to carry out advanced text analysis, and you don’t mind a little command-line work, Alexandria is the tool for you. If you’re used to working with XML, you’ll find it especially enlightening to work with a data model like TAG in which you can easily model overlapping structures, discontinuous elements, and nonlinear text without having to resort to workarounds.

News

Latest release: Alexandria 2.3 (September 2019)

Bugfixes:

Release: Alexandria 2.2 (July 2019)

New/Changed commands for the command-line app
Bugfixes:

Release: Alexandria 2.1 (December 2018)

New features:
New/Changed commands for the command-line app
Bugfixes:

Presentation

Haentjens Dekker, Ronald. Invited talk at the Workshop on Scholarly Digital Editions, Graph Data-Models and Semantic Web Technologies, Université de Lausanne, 3 June 2019.

Documentation

Below we explain how you can download and install Alexandria on your local machine, and what you need to operate it. We’ll also provide links to a comprehensive tutorial and other helpful sites.

Keep in mind that both the TAG data model and the Alexandria implementation are under development. This means that by using Alexandria you will make a valuable contribution to the development process. We therefore encourage you to try it out and share your thoughts.

About that command line…

Alexandria is a command-line tool. In practice this means that it doesn’t have a Graphical User Interface: you run Alexandria from your command line (sometimes also called the shell, the terminal, or the command prompt) and interact with it by typing out instructions in words and then hitting the Enter key. If you’re unfamiliar with the command line, you’ll find a good tutorial here or here.

Sublime Text Editor

Install Sublime Text 3, a cross-platform editor that has syntax highlighting for TAGML. We recommend you use it to view and create TAGML transcriptions; it makes your work a lot easier. Instructions on adding the Sublime package for TAGML syntax highlighting can be found here.

1. Installation

1a. Download

An up-to-date version of Alexandria can be downloaded from https://github.com/HuygensING/alexandria/releases/tag/2.4

1b. Build

Alternatively, you can build it yourself with

mvn package

The .zip in alexandria-markup-server/target contains a lib dir with the fat jar, a bin dir with the alexandria scripts for linux and windows, and an example dir.

2. Unpack the zip

Unpack the zip to a new directory of your choice. Remember the path to that directory. Now you have to make sure that your machine can always find the bin directory that contains the Alexandria code when you call it. You have three options:

2a. Create a permanent alias in your .bash_profile

Open your .bash_profile. If you’re on a Unix machine, you can type open -a "Sublime Text" ~/.bash_profile in your terminal window. This will open your bash_profile in the Sublime Text editor (of course you can use an editor of your choice).

You can create an alias for Alexandria by writing alias alexandria="<path to alexandria>". For instance, your alias could say alias alexandria="/Users/alexandria-markup-server/bin/alexandria". Save and close your bash_profile. Before the alias works, you have to resource the bash_profile: type source ~/.bash_profile in your terminal.

2b. Add the directory to your PATH

In your terminal window, type:

export PATH=$PATH:<path to the alexandria bin directory>

For example:

export PATH=$PATH:/Users/alexandria-markup-server/bin

if that’s where you’ve stored Alexandria. You can check if it works by typing

echo $PATH

in your terminal window. It should return something like the following, with the path to Alexandria directory newly added at the end:

/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:/Users/alexandria-markup-server/bin/alexandria

2c.

If you don’t want to change your path, you can create a softlink.

A soft link (also known as a symbolic link or symlink) consists of a special type of file that serves as a reference to another file or directory. You can create them on your command line:

$ ln -s {source-filename} {symbolic-filename}

For example:

$ ln -s /Users/alexandria-markup-server/bin/alexandria /usr/local/bin/alexandria

Verify if it works by running

$ ls -l /usr/local/bin/alexandria

Your output will look something like:

lrwxr-xr-x  1 veryv  wheel  5 Mar  7 22:01 alexandria -> Users/alexandria-markup-server/bin/alexandria

Notice the -> that indicates the link between the link name and the file.

Working with Alexandria

If you’d like to get started right away, take a look at an overview of the commands with which you interact with Alexandria.

We also created a tutorial. The tutorial takes the form of a Jupyter Notebook. The notebook contains blocks of text and small snippets of code: commands that you give to your version of Alexandria. You can run these commands from within the notebook. The notebook, in other words, is a secure environment for you to play around with and get to know Alexandria.

Presentations and publications