Initial description 10 October 2017
Revised 18 December 2017 and 8 January 2018
Current version 14 March 2018
This page describes the provisions for tracking the status of records in the TLRR2 project. It begins with a terse summary of the current situation, continues with high-level description (originally drafted as a proposal), and concludes with a description of the implementation approach used.
Note October 2022: this document is out of date.
After preliminary discussions of the required functionality and the desired information, the following proposal was formulated.
Add a status attribute to each trial, person, court, and procedure (and any other record types we end up adding), with values as described below.
Add buttons to the Dexter interfaces for all record types.
Values will include:
unchanged = unchanged from TLRR 1revising = some changes from TLRR 1 made, revisions not finishedrevised = revisions by responsible team finished, ready for
editing. Record is read-only for all but the editor. editing = editor has made changes, editing not finishededited = editor has completed editing, ready for publication.
Record is read-only for all participants.For trials, the expected forward moves are as follows. On all moves, an separate entry is added to the revision history with the date and a description of the move.
All trials start with status="untouched".
The first time a trial is changed by a human editor (i.e. the first time it is saved from the Dexter interface), status changes automatically to status="revising".
Further changes leave the record with status="revising".
When the responsible team is done revising the record, they click the "Save and mark revisions complete" button (aka "the DONE REVISING button"), which sets the status to "revised" and saves the record.
Later change of heart: the initial description sounds like two buttons, one labeled "Save document ..." and one labeled "Save and mark revisions complete". But the existing Save button has a lot of internal logic that we do not want to duplicate. Unless we want to spend time figuring out how to make a named action we can call from each of the two Save buttons, it will be simpler to have a Boolean flag labeled "Mark revisions complete" which is examined at Save time.
N.B. the Done Revising button (or: flag) is available whenever the status of the record is "revising" or "untouched". (The record may require only simple changes done in one pass over the text.) [Later change of heart: no one-and-done edits. Make your edit, save, open again, mark completed.]
When the editor first changes (saves) a record with status="revised", the status changes automatically to "editing".
Further changes leave the record with status="editing".
When the editor has finished checking and editing a record, they click the "Save and mark completed" button (aka "the DONE EDITING button"), which sets the status to "edited" and saves the record.
N.B. the Done Editing button can be clicked by the editor whenever the status is either "revised" or "editing". (The record may be OK without any editorial changes.)
Additional possible moves are:
Any participant can change a record's status from "revised" back to "revising". This allows recovery from erroneous clicks on "Done revising" and also for the responsible team getting cold feet.
The editor can return a record for further revision (status="revising") from status="revised" or "editing".
In the diagram below:
Blue ovals represent states in which the authors are responsible for the record; filled green ovals are states where the editor is responsible.
Solid arrows represent status changes that can be made by any project participant (blue for normal or forward, red for going backwards); dotted arrows are status changes accessible only to the editor (green for forward, red for backward).
The following parameter entity declaration has been added to the DTD to define the status keywords for trials:
<!--* status-kw, for status tracking *-->
<!ENTITY % status-kw "(untouched
| revising
| revised
| editing
| edited)" >
This parameter entity is used in the attribute-list declaration
for trial, which now reads:
<!ATTLIST trial
id ID #REQUIRED
sortdate CDATA #REQUIRED
tlrr1 NMTOKEN #REQUIRED
n NMTOKEN #REQUIRED
tlrr2 NMTOKEN #REQUIRED
status %status-kw; #REQUIRED
>
The Dexter trial editor now displays the status along with the working trial number. Prior to this change, the top of the display was handled thus:
<xf:output value="@id">
<xf:label>Trial ID</xf:label>
</xf:output>
(<xf:output value="if(@tlrr1 != '',
@tlrr1,
'Not in TLRR1')"/>)
The new code is:
<xf:output value="@id"> <xf:label>Trial ID</xf:label> </xf:output> (<xf:output value="if(@n != '', @n, 'No working number')"/>) <xf:output value="@status"/>
The design says that trials become non-editable by most
project participants when the status is revised or
editing, and non-editable by all participants
(including the editor) when the status is edited.
But trials can be returned to an earlier status for further
revision or further editing (status regression), so there must
be some way to edit the status field even in a non-editable
trial.
Several possible approaches offer themselves:
A separate form for status regression is tempting for the implementor because it would be a very simple form with only a button or two to change the status of the record. And it would keep Dexter from becoming even more complex.
But it appears that the idea of having many different tools for small tasks is more appealing to implementors than to historians. For most project participants, it seems likely that a single editing interface in which all changes to the record can take place is more attractive than multiple interfaces.
So we chose to make Dexter manage all status shifts.
To make Dexter display the record read-write or read-only
as appropriate, two xf:group elements are used,
one for the read-write case and one for the read-only case. The
basic outline is this:
... editable interface to trial ...
... read-only display of trial ...
... buttons to change status ...
]]>
Perhaps a toggle could be used instead, to avoid the duplicate test.
Note the introduction of a role-list instance
with usernames and authorizations. This could go into the
administrative document in the XQuery database, but for
the initial implementation this has not been done. A
single user is represented as follows:
<user username="cmsmcq"
role="tech"
privs="author">C. M. Sperberg-McQueen</user>
When the user saves a trial with
status="untouched",
the status value should change to revising;
similarly, a status of revised
should change automatically to editing
when an editor saves the trial.
These changes are handled by actions in the final Save button (after the user specifies an entry for the revision history).
When the status is revising
or editing, we offer a
checkbox next to the Save button:
Mark revisions as completed
Mark editing as completed
]]>
The inner (second) Save button then triggers the following actions (as well as those for automatic status shifts):
To do:
To allow the user to move a trial back to a revisable status, we need to provide buttons in the read-only presentation of the non-editable record.
Re-open for further revision
Re-open for further editing
]]>
To do:
The stylesheet for the list of all trials (alltrials.xsl) now inserts the following in each list item, before the trial's ID and number:
<span class="status {@status}"> </span>
The CSS stylesheet then assigns an appropriate background color and border for the display of the non-breaking space, so we get a small colored rectangle in the display:
/* status display */
span.status {
display: inline-block;
width: 1.2em;
margin: 0 0.5em 0 0;
border: 1px solid black;
}
span.status.untouched {
background-color: gray;
}
span.status.revising {
background-color: orange;
}
span.status.revised {
background-color: #0D0;
background-color: green;
border: 3px solid #333;
}
span.status.editing {
background-color: #0D0;
border: 3px solid yellow;
background-color: green;
border: 3px solid orange;
}
span.status.edited {
background-color: green;
border: 3px solid #0D0;
}
Last updated 29 January 2018
Photo "Foro romano in crepusculo
© 2013 by MauroPPP;
some rights reserved.