TLRR - the Dexter editing interfaces

Dexter

Note October 2022: this document is out of date.

“Dexter” is the name for an editing interface developed for use in updates to the TLRR2 database. This page describes a copy of the editing interfaces accessible to the public; they behave like those used by the project team for database maintence, with two exceptions. First, they operate on data from the first edition of TLRR (TLRR1), not from the in-preparation database of TLRR2. And second, the Save buttons have been disabled for obvious reasons.

Additional editing interfaces may also be prepared in the future (which is why Dexter got a name, rather than just being "the editing interface").

Getting into Dexter · Current status · Using the interfaces · Frequently asked questions

Getting into Dexter

Dexter has two main entry points for each type of document: trials, persons, procedures, and courts. For each type of document, there is a link below to a list of all documents of that type (and from that list any individual document can be displayed or edited), and there is also a link below for making a new document of the type.

A note on usage. In traditional database terms, each document in our document collection is a record: a collection of information about some one thing. In XML terms, each record in our database is an XML document. Both terms are used here to denote the same set of things.

List all trials
List all persons
List all procedures
List all courts
New trial
New person
New procedure
New court

To retrieve (read-only or in an editor) a single record, use the List all link and then choose a record.

Current status

The tools shown here for displaying and for editing trials, persons, procedures, and courts are now (July 2016) undergoing an alpha test by members of the project team.

Using the interfaces

At a very basic level, there are always four things one can do with any object in a database: create it, retrieve it, update it, and delete it.

Creating new records · Retrieving existing records · Editing records (Persons, procedures, courts · Trials) · Deleting records

Creating new records

To create a new record, click on the appropriate link above.

You will be presented with a form to fill in.

Procedures and courts

In the case of procedures and courts, the form is very, very simple: a text form field and an index form field. (In essentially all our current data, these are the same. We have two fields here in case they ever need to diverge.

Once you have filled in some data, a button labeled Generate ID for this document will appear. (Each of our documents has a unique identifier.) When you click on the button, the form in the Web browser will negotiate a little bit with the back-end database; first a dialog box will pop up informing you that an ID has been requested, and then after a pause another dialog box will pop up informing you that a given ID has been assigned — possibly the one requested, possibly a different one if the first is in use. (It is conceivable but not expected that instead you get a message telling you that things have gone horribly wrong. If that happens, please send MSM email with the details.) After the ID has been reserved, the Procedure ID or Court ID field near the top of the record will be filled in. Note that this field is read-only: you can see it, but you cannot change it.

Once the ID has been generated, a Save document ... button appears. When you click on it, you are asked to identify yourself and describe what changes you've made in the document. What you say will be recorded in the document's revision history, which serves to summarize what has happened to a document in the process of work on TLRR2.

Persons

The Person form is more complicated: it has fields for the individual's nomen, RE number, Praenomen, and cognomen, as well as a Text form (the form in which the person is referred to in the text of TLRR) and the Index form (the form in which the name appears in the index of TLRR1, in the order nomen, praenomen, cognomen).

In anticipation of some further re-analysis of the data, fields have been provided for Highest office and date and City of origin. These are blank for existing person records, but please provide it for new records, if you have it.

If we don't have a name for a person (e.g. all we know is "Arretina mulier" (trial 132 [ZEX]) or "adulescens" (trial 375 [YAL]), the description goes into the field labeled Description of person (in lieu of name).

The process of generating an ID for the person record and saving the record are essentially the same as for procedures and courts (q.v.).

Some complications:

Some records for names of unusual structure almost certainly have analysed the name into the wrong pieces; you will need to correct these.
Descriptions which include names of other people ("slave of X") are an open problem, on which further analysis is needed. For now, use the Description field.
The City of origin field owes its origin to what was probably a misunderstanding of a remark in the Introduction to TLRR1. It may or may not be worth distinguishing from other information in descriptions of unnamed or named people.

Trials

The new-trial form looks rather different from the forms for persons, procedures, and courts. They have all fields present, whether blank or not. The trials documents, by contrast, only contain XML elements which contain information. (Some technical people would describe the difference as being that the trials are using a colloquial form of XML, and the other documents a non-colloquial form.)

What you will see when you go to the New Trial form is essentially a sequence of buttons for adding XML elements to the document, in their approximate order of appearance in TLRR1. Each is accompanied by a description in the form, so they won't be described in detail here. The buttons also normally indicate the actual name used in the XML for the element; this is intended to make you familiar, over time, with the XML structure, so that when you look at the XML data you will recognize what you see. (XML is not that hard to understand: everything has a label at its beginning and at its end, precisely to make the structure so painfully explicit and clear that even software can understand it. You may find it aesthetically challenging, but you should not find it difficult to understand. At least, that's my hope.)

The one element for which there is no Add button is the list of sources; that is always present, though initially of course it does not contain useful values.

Once you add one element (e.g. a defendant group), new buttons will appear to allow you to add possible child elements (in the case of a defendant group, these will be the defendant, the advocate for the defendant, and witnesses for the defense; other top-level elements will of course have different possible child elements).

Generating an ID for the trial document and saving the document is roughly the same as for the other kinds of records, but the many Add and Edit buttons you press while editing a trial make some notes on what changes you've made to the document, so when you are asked to record what changes you made, there will be notes in a kind of telegraphic style reminding you that you added this and that element, and edited this or that element. (You should turn these raw notes into comprehensible prose.)

Retrieving existing records

The All trials, All persons, All procedures, and All courts pages provide lists of all the documents we have of the types indicated. If you can identify the document you are interested in from the short description provided, you can display it, display its XML form, or edit it, by clicking on the appropriate links following the short description.

More powerful searches for specific records can be performed with the search interfaces Balbus and (if you know a little XPath) Ancilla. These aren't conceptually part of Dexter, and I won't attempt to describe them here. (They are designed not to need documentation; let me know if they do.)

Editing records

Persons, procedures, courts

Editing a person, procedure, or court record is relatively straightforward. All fields are present and visible; change the one(s) you want to change, click Save, describe what changes you made and why, and click Save again.

The trials form

For every possible top-level section in the trial record (in XML terms, for every possible child of trial), the editing form displays either the current data in that section, with an Edit button, or else an Add button if the section is not currently present. Similarly for second-level elements like defendant or prosecutor: if they are present, they are displayed, and if not, an Add button is displayed instead. Delete buttons for each element are (or should be) also provided; they are made visible by clicking on the Edit button for the element in question.

Some elements in the XML representation are present solely to hold and group other elements: the defendant group (defGrp), plaintiff / prosecutor group (ppGrp) and other top-level parts of the trial record are examples. Buttons are used to allow the user to add appropriate child elements to these grouping elements.

Other elements in the XML representation can contain textual data (i.e. English prose), intermixed with italic phrases, footnotes, superscripts (rare, but necessary for some bibliographic references), and references to specific trials, persons, procedures, and courts. (References to specific ancient authors, works, and/or passages will join this list in due course, but not imminently.)

For each of these textual elements (the technical term is elements with mixed content, which may appear here and there in the user interfaces), there is more than one editing interface, currently identified by arbitrary names. Those made accessible in the current version of the trials editor are:

Ianua

This is a very primitive interface by most measures, but very powerful: it displays the raw XML form of the element being edited, and allows you to change it in any way you like.

You must preserve the well-formedness of the XML when editing the raw XML. If you make a mistake, the browser is likely to signal its displeasure with an uninformative message like “Unable to parse XML”. You are currently on your own when it comes to fixing the problem. (I hope to develop a more forgiving XML parser when time permits, to provide better diagnostics and to repair errors when possible. But this is not imminent.)

For users who don't understand the XML structure, the Ianua interface is likely to be frustrating.

For users who don't want to understand the XML structure, Ianua is likely to be even more frustrating. But since the XML structure is a representation of the structure of the information and the text, not wanting to understand the XML structure would be like not wanting to understand the work we are doing. So I don't expect any participants in the project to fall into this category.
Lacrimae

The Lacrimae interface provides a more structured display of the XML structure: it shows the boundaries of each element in the structure, and presents the textual data in text boxes, where it can be edited directly.

Existing elements and text nodes can be deleted as a whole; to delete an element, click on the Del button which appears at the end of the line displaying the element's start-tag. To delete a text node (labeled #), click on the Del button at the end of the line. N.B. if you delete an element, you delete all of its contents as well. There is currently no Undo facility; be careful what you delete!

New elements and text nodes (blocks of textual data) can be inserted within an element (as the first child of the element) or after any element or text node; click on the Ins button at the end of the line to expose the list of what can be inserted, where.

Among the known gaps in this interface at the moment are the following, listed roughly in the order I expect to be able to remedy the gaps:

The read-only display of fields may not yet handle all fields; fields not yet handled by the stylesheet will display in red, in XML notation. This is my way of making the gaps in the stylesheet more visible. Over time, I'll get around to all of these, but if red text persists, feel free to let me know what red text you are seeing.
There is no facility for reordering elements, other than inserting a new element at the desired location, giving it the desired content, and then deleting the element in the original location.
The facilities for selecting persons, procedures, courts, and trials from the lists of known persons, etc. are currently a little awkward. Suggestions for improving the interface are welcome.
There are no straightforward facilities for untagging elements (e.g. removing italics from a phrase), renaming elements, or splitting elements or text nodes into multiple pieces.

Deleting records

There are currently no facilities for deleting entire documents. When we have them, they will be on separate pages, so the Delete document button doesn't get hit by mistake. This button, when it exists, will not actually delete the document; instead, it will add an entry to its revision history saying that the document has been deleted, and change the name of the document's main element from trial to deleted-trial, person to deleted-person, etc. Deleted records will still appear in the list of all records. If we need something to be really and truly deleted from the database, manual intervention by the database adminstrator (MSM) will be necessary.

Frequently asked questions

None so far.