Oracc GUI
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.github
doc
python
resources
src
.gitignore
.travis.yml
LICENSE.txt LICENSE was not a markdown but txt. Jun 13, 2016
README.md
pom.xml
requirements.txt

README.md

Nammu: Desktop GUI for ORACC

To run Nammu on your computer, you can download it from here and just double click on it to open it.

What is ORACC?

ORACC is the Open Richly Annotated Cuneiform Corpus. It provides open-access, standards-based publication platforms, research tools and teaching resources for Assyriology and ancient Near Eastern History, hosting around 40 academic research projects worldwide.

ORACC has become established as one of the core online resources in the world of ancient Near Eastern studies. It originated in an AHRC-funded research project Prof. Eleanor Robson ran at the University of Cambridge several years ago and is now continuing to run from University College London in collaboration with University of Pennsylvania (Philadelphia).

What is Nammu?

Nammu is a desktop GUI that enables ORACC content creators to edit, check and upload transliterations of Sumerian texts in the form of text files in ASCII Transliteration Format (ATF). It is being developed as a text editor with extended functionality.

At the time of writing, ORACC content creators use an Emacs plugin for edition, validation and lemmatisation of ATF files. This plugin can only be installed as part of Emacs, which has a steep learning curve.

With Nammu, we intend to make a user friendly tool that would replace the use of the ORACC Emacs plugin. This will help lower the access barriers to the use of ORACC, enabling more projects to adopt it.

Nammu is currently being developed by the UCL Research Software Development Group.

Validation and lemmatisation of ATF files

In order to validate ATF files, Nammu uses two approaches:

  • Online validation against ORACC server, configurable on the settings menu.
  • Offline validation using pyORACC, the new ATF parser developed by UCL RSDT.

Lemmatisation can only be done online with the ORACC server.

Validation and lemmatisation against the ORACC server

The ORACC server is hosted at University of Pennsylvania (Philadelphia) and maintained by Prof. Steve Tinney. The ORACC server provides SOAP web services for validation and lemmatisation of ATF files. Nammu acts as a SOAP client, requesting the server to validate and lemmatise ATF files, and then presents the server output in the GUI.

Validation with pyORACC

Validation against the ORACC server requires the user to have Internet access. Since this is not always the case, the UCL RSDG is also developing an ATF parsing tool to provide offline initial ATF validation. This tool is called pyORACC and you can find more information about it here.

Nammu uses pyORACC in two different ways:

  • Syntax highlighting: This feature allows for users to detect errors while they are typing the text. This type of validation helps users check for text correctness like spelling errors in keywords, word ordering in each line, etc. It won't however highlight errors in the transliterated words, lemmas or translations.
  • Offline validation (under development): Users can select to do an offline validation using pyORACC when they don't have Internet access. This will return error messages coming from pyORACC and presented in the GUI to guide the user on how to correct them.

How to run Nammu

To run Nammu on your computer, you can download it from here and just double click on it to open it and use it.

If you find any problem trying to open it, have a look in the Troubleshooting section.

Default keystrokes

There's a set of default keystrokes for all actions that can be done with Nammu:

Action Keystroke
New File Ctrl/Cmd + N
Open File Ctrl/Cmd + O
Close File Ctrl/Cmd + W
Save As Ctrl/Cmd + E
Save File Ctrl/Cmd + S
Validate Ctrl/Cmd + D
Lemmatise Ctrl/Cmd + L
Undo Ctrl/Cmd + Z
Redo Ctrl/Cmd + Y
Find Ctrl/Cmd + F
Find next Ctrl/Cmd + G
Replace all Ctrl/Cmd + A
Replace one Ctrl/Cmd + R
Show Help Ctrl/Cmd + H
Split Editor Horizontally Ctrl/Cmd + .
Split Editor Vertically Ctrl/Cmd + ;
Syntax Highlight Switch Ctrl/Cmd + T

These are in your settings file and will be editable from the settings menu on a later release.

Getting help

If you run into trouble, or have any questions or suggestions, you can get in touch with Nammu's developers by creating a new issue in this repository and telling us about your problem here.

Please follow the guidelines to help us better understand and reproduce your problem.

Known problems and troubleshooting

If you try to open Nammu and it doesn't work, it might be that you don't have Java installed. You can check if you do by opening a terminal and typing:

java

If that command is not recognised, then you'll need to download and install the Java Runtime Environment (JRE). You can find the appropriate JRE installable file for your operating system here.

If you keep having trouble, you can also run it from the command line, like this:

java -jar /path/to/nammu-1.0.0.jar

Where /path/to/ reflects your local path to where the nammu-1.0.0.jar file has been downloaded. This will output a clearer log message about what the problem is.

Known problems:

  • Nammu doesn't validate or lemmatise properly when filenames include a space.

A full list of issues can be found here.

If you have any other suggestions, new features you'd like us to work on, or any other comment, please let us know by creating a new issue here.

Nammu's configuration for advanced users:

Nammu's config and logging

The first time Nammu is run, it will create automatically a hidden folder in your home directory ($HOME in Unix machines and %USERPROFILE% in Windows machines) called .nammu. Alternatively, this folder can be installed elsewhere by setting a new environment variable called NAMMU_CONFIG_PATH that points to the desired location where the .nammu folder and its contents will be stored.

This folder will contain a log file with debug information output by Nammu and a YAML file containing some configuration on how the logging works.

You can see here the default logging configuration.

There is also a configuration file for shortcuts, preferred working directory, preferred list of ORACC projects, etc. This will be fully editable from Nammu, but for now only working directory and lemmatisation server can be edited from the settings window.

Notes on Nammu's software development

Nammu is being developed in Jython, an implementation of the Python language designed to run on the Java platform. The installable for Nammu is a JAR file containing Nammu's code as well as all the necessary Java and Python libraries to run it, like pyORACC, logging, etc.

JAR files can be run in any platform as long as the Java Virtual Machine has been installed. It doesn't require any other extra configuration.

Requirements

Nammu is designed for and tested on Java 8. It is not currently possible to build the jar file using Java 7 due to problems with jython-swingutils. For more information on this issue and to follow progress in resolving it check out this issue.

Contributors

If you want to contribute to the code, or you want to install and run the code to customize it instead of just downloading the JAR file, you will first need to install a few requirements:

  • Maven, a project management and building tool for Java. This gathers all the dependencies of the project (e.g. Jython, pyORACC, logging, etc.), runs tests, compiles the code in a JAR file, etc.)
  • The Java Development Kit (JDK).
  • Optionally git so you can clone the repo instead of downloading it and contribute to it if you like.

To obtain the code and run it, you can follow these steps:

  1. Clone the repo in your computer: git clone git@github.com:oracc/nammu.git
  2. Download and install the JDK.
  3. Download and install Maven following instructions.
  4. Run the following Maven command to install the project and clean the output from previous executions:
mvn clean install
  1. This will create Nammu's jar in the target folder. Then you can execute it like this:

java -jar  target/nammu-1.0.0.jar

  1. You can also run Nammu in development mode from the console. See instructions: https://github.com/oracc/nammu/wiki/Running-Nammu-from-a-console

If you find any problem or need more information, you can create an issue here.

License

Nammu is free software and has been licensed under the GNU General Public License. You can read the full license text here.

If you want to reuse Nammu's code and have any concerns about the implications of this license, please get in touch with us at rc-softdev (at) ucl.ac.uk.

Links of interest