I. Basic transcription — a two-minute
If you've installed Diplomat on your computer, you should be able to
start it by clicking (or double-clicking) the icon. When Diplomat
starts, it shows this panel:
Under the File menu, select Open ... and choose
your image file, browsing to the appropriate folder if necessary.
When you click the Open button, two windows will open on your
screen: the image window on the left and the transcription
window on the right:
Click anywhere on the image window or its title bar to select it.
Choose the first line you want to transcribe. (It can be any
line; it needn't be the first line of the passage.) If the whole
line isn't visible in the image window, zoom in and out using + or -
keys respectively, and use the scroll bars to bring the whole line into
view. Click-and-drag from one corner of the line to the opposite
corner; when you release you'll have drawn a box around the line.
You can adjust the boundaries by clicking and dragging near any corner,
or shift the whole box by clicking and dragging inside the box.
Clicking anywhere else on the image will erase the box and allow you to
When you've drawn a box tightly round the line, press return.
typing window will appear directly under the selected line
into which you can type your transcription of the line. If the
characters in your typed text are too far to the left or right of the
corresponding ones in the manuscript image, press the up and down
arrows on the keyboard to resize the typing window until they line up.
When you've finished typing the line, press return. The
typed line now becomes part of the transcription, and is displayed in
the transcription window.
This is the basic cycle of transcribing with Diplomat:
- Select an image line by dragging a box around it.
- Press return to display a typing window for the line.
- Type the line into the typing window.
- Press return to incorporate the line into the
If you click on a line in the transcription window, the image window
will show the corresponding line from the manuscript. If you
press return now it will present a typing window already
filled with the line as you had previously typed it. You can
change this line in any way, and then press return to put the
line into the transcription, or esc to discard the changes
and keep the
line as it appeared before. You can also erase the contents of
the typing window and press return; this will remove the line
transcription and renumber the other lines accordingly.
Saving and exporting
If you invoke File→Save, Diplomat saves
the text you've written and the links between transcribed text and
manuscript lines. This lets you carry on working in a subsequent
Diplomat session from when you saved. But the saved work is in a
format that only Diplomat can use; to produce a text file of your
transcription that can be used outside of Diplomat you need to invoke File→Export
text. This will write the text to a .txt
file with the same name as the image file, in the same folder.
For example, if you are transcribing from an image file called 138v.png,
138v.txt in the same
You might like to practise transcribing some lines from your manuscript
by the above method before going on to the next instructions.
Remember you can always change what you've done, so you can go back
over this practice work later to make use of some more advanced
II. Going further
The typing window has a button labelled Insert (which can
invoked by the shortcut ⌘I on a Mac or ctrl-I on any other
computer). This brings up a menu; selecting Character
menu brings up a sub-menu of characters that when clicked on will be
inserted into the text in the typing window.
Initially this menu is empty; you can populate it with useful
characters by invoking File→Configure→Character
menu. For example, suppose your transcription needs upper-
lower-case thorns and yoghs. Start by invoking File→Configure→Character
This will bring up a configuration window:
Click the + button to add a new menu entry; a form will be displayed:
At the top are three fields. You can either cut-and-paste the
desired character from somewhere else into the Character
field, or type its Unicode number in the Unicode field, or
give its HTML code
(without the “&” and “;” — these are
already supplied) in the HTML entity field. The other
two fields will be set automatically:
Then give a brief description of the character in the Description
field; this will be the hint that's displayed when you hover over the
character in the menu:
Click Done, and the character is now in the menu. You
can add more characters the same way, or edit or delete them by
entry and clicking ✎ or - respectively. You can rearrange the
order in which they appear by
selecting an entry and clicking ▲ or ▼. Clicking the ---
button will add a line in the character menu to group entries.
Now the Insert→Character
menu on a typing window will produce the selection of characters that
inserted in the text:
Some characters have no Unicode representation; typically these are
abbreviations. To allow these to be transcribed easily and
uniformly, they can be put into the Abbreviations menu which
resides under the Insert button.
Like the Character menu, this is initially empty. To
put a character into this menu, select it by drawing a box tightly
around it in the image window:
But instead of pressing return to bring up a typing window,
press a (for “abbreviation”) on the
keyboard. This form
- Adjust the contrast and brightness until the character is as
close as possible to a black figure on a white background.
- Type a Description of the character — this is
what will appear as a hint when you hover over the abbreviation in the
- Type a Transcription of the character — this
is how you would like the abbreviation to appear in the transcription
window, and when exported as a plain text file.
- Optionally, type the XML that you would like generated
for the abbreviation when it is exported as an XML file.
Click Done, and this character will now be in the Abbreviations
menu. You can now use that menu item to insert the figure into
the text in a typing window:
and it will appear in the transcription window as the string you gave:
The box around the transcribed text indicates that this is an expanded
abbreviation; click-and-hold over this box to see what the original
figure looked like:
Also under the Insert button is the Annotation
entries Addition, Supply text, Milestone,
and Note. (The colour coding here uses yellow to denote
scribal activity, green to denote editorial activity.) Each
brings up a form for attaching markup information to the text.
For example, presing Supply text brings up this form:
This is for the editor to supply some missing text. Clicking on
the arrow on the Reason field displays a number of possible
reasons for this being necessary; you can select one of these or type
in one of your own.
Similarly, the Source field has built-in entries to select,
or you can type something in. Editorial insertion is
where you type the text you are supplying:
Click Done, and a green mark in the typed text will show
where the insertion has gone.
Move the mouse over the green mark until it becomes red; then
click-and-hold to see details:
or double-click to bring the form back for you to make changes.
The text will also be outlined in green in the transcription window
where you can click-and-hold to see details:
The Annotate button on the typing window (with keyboard
shortcut ⌘A or ctrl-A) brings up a menu for marking up
regions of text rather than points in the text. This button is
enabled only when you have selected some text in the typing window:
Experiment with all the menus under the Insert and Annotate
buttons. (You can easily delete the notes they produce by
deleting the corresponding text or marks in the typing window.)
The range of marking-up they produce, and how that is displayed in the
windows and saved as plain text or XML, is fixed in this version of
Diplomat. In future versions these will be user-configurable,
much as the Character and Abbreviation menus are.
If the colour that shows your selected region on the manuscript image
doesn't show up well against the colour of your manuscript, you can
change it with File→Configure→Mask colour.
Files and folders
Diplomat expects all the manuscript images in your transcription
project to be in a single folder. When you configure the mask
colour and the Character and Abbreviation menus,
information is saved to a file called config.dip in the same
folder. These menus are then used for all the manuscript images
in that folder.
All saved and exported transcription information is put into files that
share their name with that of the image file. For example, if you
transcribe from an image called 138v.png,
save its transcription information in 138v.dip,
plain text to 138v.txt, and export XML to 138v.xml;
~ (for example 138v.dip~) which you can
When you open a manuscript image that you have worked on before, rather
than using File→Open you can use File→Open
recent which is a menu of the last six images you've worked on.
Diplomat produces line numbers automatically based on how high or low
the selected region of the image is. This works well for text in
a single column, but if there are two or more columns (or two or more
pages) on one image it won't work properly. The simplest way to
deal with this is to make a duplicate copy of each image file for each
column it contains; for example if 138v.png shows a page with
two columns, make a copy of the file and rename them 138va.png
and 138vb.png respectively. Then use the former file
when transcribing the first column, and the second (identical) file
when transcribing the second column.
Although Diplomat creates line numbers automatically and changes them
when new lines are inserted or deleted, it does allow you to number a
line as being part of the previous line (e.g. 29a, 29b), or to assign a
range of line numbers (e.g. 31–35) to a single line of transcription.
To change a line number, double-click on the
number in the transcription window. This will bring up a small
Click on the arrows next to the number to give a smaller or larger
number range to this line. When you click Done to save
the change, the other lines in the transcription will be re-numbered
Selecting File→Export XML will write your
transcription to a file, with XML tags to
indicate line numbers, annotations, and abbreviations. The latter
are represented according to the configuration you give when you set up
the Abbreviations menu; other encodings are fixed (but they
will be configurable in a future version of Diplomat).
Diplomat works with files in most image formats: PNG, TIFF,
GIF, JPEG, BMP, CUR, ICO, IM8, PCT, PCX, PICT, PSD, RAS, TGA, XBM,
XPM. If you have a choice, you should avoid JPEG; it compresses
image data in a way which isn't well-suited to pictures of written or
printed text. PNG is suitable; it does some data compression but
doesn't degrade or corrupt the image as JPEG can. TIFF does no
compression, so it doesn't damage the image, but the resulting files
can be very large. This may or may not be a problem depending on
how many images you've got and how fine the resolution is.
Diplomat can't read PDF files, so if your images are in that format you
will need to convert them to PNG or TIFF using Gimp or Photoshop or
another suitable program.
III. More help
This is an early test version of Diplomat, with rudimentary
instructions, so you're bound to need help! Email me at
3 December 2010