README.org

Emacs Literate Ontology Tool (ELOT)

What

This repository contains a template for writing OWL ontologies as Org Mode documents, with supporting functions and scripts.

Check out the files pizza.org, bfo-core.org, maintenance.org for example ELOT files.

ELOT works on Windows, MacOS, and Linux (tested in WSL).

Literate programming is a paradigm where the creator of some technical artefact focuses on the explanation and readability of each technical construct, rather than its formal machine-readable definition. The machine-readable artefacts are then extracted through a process called “tangling”.

ELOT takes inspiration from this paradigm and uses the excellent Emacs Orgmode plain-text format to create an author- and reader-friendly ontology authoring environment. Ontological constructs are generated from narrative sections and Manchester Notation (OMN) fragments. Diagrams are generated from Turtle examples or SPARQL queries by using the rdfpuml tool. The tool then extracts ontological definitions (OMN or Turtle) and documentation (HTML or PDF).

Prerequisites in brief

• Download ELOT using Git to easily obtain updates
• Use a recent version (29.x) of Emacs
• For viewing your ontologies, install version 5.6 of Protégé Desktop
• Install Java to enable advanced features
  • Turtle output, ontology metrics, and more: install ROBOT
  • Ontology diagrams: install PlantUML and rdfpuml

If you are new to Emacs, the book Mastering Emacs is highly recommended.

Installation

Get Emacs

ELOT has only been tested on recent versions of Emacs. As of 2024-04, version 29.3 is the latest. See the GNU Emacs download page.

For Windows users: download Emacs from the emacs-29 for Windows directory. The package named emacs-29.3-installer.exe will work fine. It’s preferable to install into a folder that doesn’t contain spaces.

For Linux users: ELOT has been tested on WSL 2 (Windows Subsystem for Linux). It’s recommended to

• upgrade to Ubuntu version 22; see the guide at askubuntu.com.
• compile Emacs to obtain the latest version: see the guide at hubisan/emacs-wsl.

For MacOS users: See the GNU Emacs page.

Install ELOT in Emacs

ELOT is in active development and will see frequent updates. For easy access to these updates, you should clone the ELOT repository using Git.

The following steps will get you started editing OWL ontologies.

1. Create a directory for local Emacs add-ons in your home folder, named elisp (on Windows, that will likely mean c:\Users\myname\elisp\).
2. Clone ELOT into the elisp folder using your Git client. If using a terminal for Git, the following will do it.

   cd elisp
   git clone https://github.com/johanwk/elot.git
       

   You should now have a subfolder of elisp called elot.

3. Ensure ELOT is loaded when Emacs starts up.
   • For new Emacs users: find the file elot-init.el inside the elot folder, and copy it to a new file named .emacs in your home folder, then restart Emacs. You should now be looking at a basic, working Emacs configuration.
   • Experienced Emacs users should open elot-init.el and look at the list of packages that are required. Add ~/elisp/elot/elot-package/ to your load-path.

Install ELOT auxiliaries

ELOT relies on external software programs to query your ontologies and produce diagrams. These need to be downloaded.

Preparatory steps, if needed:

1. Create a directory named bin in your home folder: you will download programs to this folder. On Windows, that will mean c:\Users\myname\bin\.
2. Ensure the bin folder is on your PATH, so the programs can be found by ELOT. On Windows, use the Control Panel to edit Local Environment Variables and add c:\Users\myname\bin\ to the list.

Get the tools:

1. The ROBOT tool is highly recommended for ELOT. Download robot.jar from the ROBOT releases page to your bin folder.
2. The PlantUML tool is needed for diagrams. Download the latest version from PlantUML Downloads (tested with plantuml-1.2024.3.jar) to your bin folder. For convenience, rename it as just plantuml.jar (on Linux, make a symlink).
3. The rdfpuml tool will produce great-looking diagrams for ontologies.
   • On Windows, download rdfpuml.exe to your bin folder.
   • On Linux or MacOS, clone the repository to your bin folder, then add ~/bin/rdf2rml/bin/ to your PATH. Install Perl modules as listed in the rdfpuml installation guide.

     cd ~/bin
     git clone https://github.com/VladimirAlexiev/rdf2rml.git
             

Quick start using ELOT

Adding an ontology

After the installation steps, it’s wise to restart Emacs!

Open the familiar Pizza ontology from elisp/elot/pizza.org for an example of what an ELOT file will look like.

To create a new ontology, do this in Emacs:

• Select a directory that you want to work in. Open a new Org Mode file, for instance myontology.org.
• Insert the ELOT template for a document header. You can do this in two ways:
  • Press the F4 key. A menu is displayed at the bottom of the Emacs window. The letters in blue represent key sequences that will call up templates or execute commands.
  • Type the same sequence (including <) at the beginning of a line and press TAB.

• Use odh (“ontology document header”) to call up the document header template. Answer the prompts, and a header is produced, like the following.

  # -*- eval: (load-library "elot-defaults") -*-
  #+title: My new ontology
  #+subtitle: An OWL ontology
  #+author: John Doe
  #+date: WIP (version of 2024-04-04 12:34)
      

• Insert the ELOT template for an ontology skeleton: Below the header, press F4 and then ods. Answer the prompts – be ready to provide namespaces/prefixes for your ontology and the resources it will contain. You should see something like this screenshot:

Now create an OWL file from your new document.

• Press F4 and then t, to “tangle” the ontology to a file. The ontology will be in OWL Manchester Syntax, e.g., with filename myontology.omn.
• If you have installed ROBOT, a Turtle file named myontology.ttl will also be available.
• Have Protégé ready, and open the ontology file to inspect it.

• Export to an HTML document with F4, then the h key. The document will open in your web browser.

Adding classes and relations

• Navigate to the Classes heading
• Press F4 followed by ocp to insert headings for defining primitive classes, with some appropriate annotation properties added. Hit ocd for non-primitive classes. The templates reveal the ELOT authors’ preference for the Industrial Ontology Foundry Annotation Vocabulary (IOF-AV).
• Navigate to the Object properties heading
• F4 followed by op will insert a relation (object, data, or annotation property).
• The screenshot shows how checkboxes are included for tracking progress..

Adding annotations

ELOT makes it easy to add annotations to both annotations and axioms: just put them in a sublist. In this screenshot, two annotations are added to the “transitive” characteristic axiom:

Querying the ontology

• Navigate to the Prefixes heading and insert a new heading named “Queries”.
• Hit F4, then obs to insert a SPARQL select code block. Write a query over the ontology.
• Hit C-c C-c to run the query.

Making a diagram

• Hit F4, then obc to insert another query, this time SPARQL construct.
• Write a query and hit C-c C-c to run it.

• Hit F4, then obd to insert an rdfpuml diagram block.
• When prompted, provide the name of the Turtle source (the name of the construct query) and the figure caption.
• Place the cursor on the row of the #+call: and hit C-c C-c. A diagram is generated.

• Hit F4, then h to view the query results and diagram in your browser.

Display labels instead of identifiers

ELOT can display readable labels instead of prefixed identifiers (which are unreadable if the identifiers are not informative), and offers quick search across the ontology resources.