Diplomat instructions

I. Basic transcription — a two-minute lesson

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 start again.

When you've drawn a box tightly round the line, press return.  A 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:
  1. Select an image line by dragging a box around it.
  2. Press return to display a typing window for the line.
  3. Type the line into the typing window.
  4. Press return to incorporate the line into the transcription.

Making changes

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 changed 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 from the transcription and renumber the other lines accordingly.

Saving and exporting

If you invoke FileSave, 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 FileExport plain 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, exported text will be saved in the file 138v.txt in the same folder.

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 Diplomat functions.

II. Going further

Non-keyboard characters

The typing window has a button labelled Insert (which can also be invoked by the shortcut ⌘I on a Mac or ctrl-I on any other computer).  This brings up a menu; selecting Character from this 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 FileConfigureCharacter menu.  For example, suppose your transcription needs upper- and lower-case thorns and yoghs.  Start by invoking FileConfigureCharacter menu:

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 selecting an 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 InsertCharacter menu on a typing window will produce the selection of characters that can be inserted in the text:

Scribal abbreviations

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 will appear:

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:

Editorial additions

Also under the Insert button is the Annotation menu, with 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.

Mask colour

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 FileConfigureMask 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, the configuration 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, Diplomat will save its transcription information in 138v.dip, export plain text to 138v.txt, and export XML to 138v.xml; all in the same folder.  It also creates backup files whose names end with ~ (for example 138v.dip~) which you can ignore.

When you open a manuscript image that you have worked on before, rather than using FileOpen you can use FileOpen recent which is a menu of the last six images you've worked on.

Multiple columns

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.

Line numbering

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 number-renaming window:

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 accordingly.

XML export

Selecting FileExport 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).

Image formats

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 email address

3 December 2010