Using the Editor

TEI Elements

In TEI, blocks of text are marked as “elements”. There are hundreds of types of elements, but in a given project you might only use a dozen of them. Different elements are used to describe different textual phenomena. For example, there is an element called p which marks a paragraph. div marks a division of the text, such as a chapter. pb can be used to mark the beginning of a page.

Each of these elements may possess certain attributes. In the TEI Guidelines and in this manual, an attribute name is prefixed by an @ symbol to differentiate them from elements. For example, lines in a poem might be numbered using the @n attribute. Or an image may be associated with text with the @facs attribute.

Elements have rules that they must follow in order to be placed logically in a text. TEI’s rules describe which elements may be contained by other elements. Each element also has a set of attributes which may be associated with it. The TEI Guidelines discuss in detail how to use each element. The documentation and rules for each element are displayed in FairCopy.

In FairCopy, we further distinguish between elements that describe the structures of a text, phrase level features, and elements that appear at a single point. We call these structure elements, marks, and inlines respectively. We’ll discuss how to place each type of element in a moment, but first let’s take a look at the toolbar along the top of the editor window.

Editor Toolbar

The Editor Toolbar is where you can access functions to add and remove elements from the text. There are also a number of familiar editor shortcuts and, of course, the save button.

The first three buttons on the toolbar are the most important. The palette button allows you to summon and dismiss the Element Palette, which is used for placing structure elements. The marker is used for adding phrase level mark elements. The stamp is used to place inline elements. Each of these are discussed in more detail below. These buttons are enabled only when the appropriate selection is made in the editor. For example, you must highlight a passage of text before you can use the marker.

Next up, the eraser, which erases the selected element. Note that if it is a structural element, this will also erase its contents. Use the undo and redo buttons if you make a mistake. You can also use Ctrl+Z and Shift+Ctrl+Z, respectively.

The remaining elements are convenient shortcuts for some common functions. The bold, italic, and underline buttons add a hi or highlight element with the @rend attribute set to bold, italic, or underline. The link creates a ref element. The speech bubble creates a note. If you select a phrase and then click on this button, it will create a ref and a note, with the ref linked to the note.

The “Edit Properties” button allows you to change the display name and ID of the current resource. The Save Button becomes active whenever the document has been changed. Note that you must save a document for it to be reindexed for search.

Structure Elements

Structure Elements describe the structure of a text, such as the opener and closer of a letter, the lines of a poem, or the stage directions in a play. These structures are always visible to the left of the document’s text.

The darker bars are called hard nodes in FairCopy. These are structure elements which may only contain other structure elements. This can be helpful to know when figuring out how to place new elements. The lighter colored elements (soft elements) can contain other structure elements or spans of text.

There are two ways to add new elements to a text. When typing in the editor, pressing the Enter key automatically introduces another soft node of the same type as the presently focused node. Pressing Ctrl+Enter will also create a new parent element.

One can also add a new element by using the Element Palette. One can summon the Element Palette by clicking on the palette icon on the toolbar (Ctrl+1). The elements on the palette are all structure elements and they are organized into groups. These groups and the elements in them can be customized in the project settings (see “Working with Schemas”). Mousing over the elements (or navigating them using Tab and the arrow keys allows you to review the description of each element.

To add an element from the Element Palette, you can grab it and drag it to the desired position in the structure tree. The surrounding elements will highlight red if it is an invalid placement or green if it is a valid place to put this sort of element. You can also accomplish this by selecting an element in the tree and then using Ctrl+Arrow Keys to specify the position of the new element.

Clicking on a bar in the structure tree selects the element. You can use the arrow keys to move the selection throughout the tree. Using the Right Arrow key on a bar that encompasses a span of text moves the selection into that text. Using Shift+Tab while in the text selects in encompassing structure element.

You can also move existing elements within the tree. Select the element first and then use Ctrl+Arrow keys to move it around. In some cases, the element may hop over an element you wish it to go into. Use Shift+Ctrl+Arrow keys in this case to enter that element. FairCopy will not allow an element to be moved into an invalid position and as a result, some movements will not be possible.

To remove a structure element, select it and then press the Delete key or use the eraser button on the toolbar. Note that this will also delete the contents of the element.

Mark Elements

Mark Elements are placed using the marker menu (Ctrl+2) on the toolbar. First, select a span of text. Then, select the desired element from the marker menu. The marker menu allows you to review the description of each element. Some elements on the menu may be disabled if these elements are not valid at the selected position.

Once you place a mark element, you can select it by moving the editor caret into that span of text or by clicking on it. To remove the mark from a span of text, select the area to be erased and then use the eraser button (Ctrl+4). Please note that you can use the eraser to adjust the bounds of a mark or to split it into multiple marks. Any number of marks can be layered on a single span of text. FairCopy computes the correct markup for these marks automatically when exporting to XML.

Inline Elements

Inline Elements are placed using the inline menu (Ctrl+3) on the toolbar. To place an inline element, move the editor caret to the desired position. Then, select the desired element from the inline menu. The inline menu allows you to review the description of each element. Some elements on the menu may be disabled if these elements are not valid at the selected position.

Once you place an inline element, it can be moved around by editing the text surrounding it. It can be selected by clicking it or using the arrow keys to move the caret to it.

Some inline elements, such as the note element, contain text that is either not part of the flow of the reading text or provides a choice between more than one possible reading. In these cases, a sub-document editor appears when the inline element is selected. This sub-document works just like the main document, accepting structure, mark, and inline elements.

Mixed Elements

Some elements can be used both at a phrase level and as structure elements. An example of this are the add and del elements. You can record the addition and deletion of both spans of text and entire structures. These elements appear on both the structure and mark menus. Additionally, inline elements may be placed between structure elements. You can add inlines to the structure palette and add them in this way to the text.

Attributes

All elements may also possess zero or more attributes. Attributes can be used to further describe the element. All elements of a given type share the same list of attributes within a given project. You can add or remove attributes from the element using the “Add Remove Attributes” button. This brings up a dialog that allows you to select the attributes you wish to assign to this element. If an element already has a value for a given attribute and you remove that element, the attribute and its value will still appear unless you remove the value. A validation error will be displayed where this is the case. See the “Working with Schemas” section for more information.

Next to each attribute is an information button which can be used to popup the documentation for that attribute. Every attribute has a data type that FairCopy uses to ensure the value is valid. Some attributes and data types have special behaviors. These are described below.

Special Attributes and Data Types

IDs may be assigned to any structure or inline element. The boundaries of mark elements are computed when it is exported and thus it is not possible to assign them IDs. IDs are exported as @xml:id, which are unique per XML element. Use the@n attribute in this case to label individual phrase level features if necessary, or use the structure version of the element in question (see “Mixed Elements”, above).

Assigning and Referencing Unique IDs

You can give an element an ID by clicking on the Assign ID button in the upper right hand corner of the Element Inspector. IDs must be unique to the resource they are in. If the resource is part of a TEI Document resource, the ID must be unique within that TEI Document. See the “Exploring Resources” section for more information.

Attributes with the teidata.pointer data type can hold URIs that reference any resource. They can also contain relative URIs that point to resources within your FairCopy project. These relative URIs are displayed in an autocompleting dropdown menu when you select an attribute of this type. Any element with an ID will be listed here as well as all surfaces and zones found in Facsimile resources. (See “Working with Images” section)

When an ID is within the same resource or TEI Document as the attribute that references it, it can be expressed with the shorthand #<ID>. For IDs in other resources or TEI Documents, use the format <resource ID>#<ID>.

The @rend Attribute

The @rend attribute can be use to affect the appearance of a given element within the editor. The following values can be used in any combination to format an element:

• uppercase
• italic
• bold
• red
• green
• blue
• purple
• orange
• brown
• gray
• small
• medium
• large
• underline
• line-through

The @xml:lang Attribute

You can specify the language in which the contents of a given element are written using a language tag. Please see the TEI Document for more information on language tags.

For text written in right-to-left (RTL) reading languages, FairCopy will display the text right-to-left if a supported language tag is specified. The currently supported RTL tags are:

• he
• ota
• fa
• ar

This property is inherited by elements lower down the tree. So, if an entire document is in one language, setting the @xml:lang attribute on the root element will be sufficient. Child elements may override the inherited language setting, so if there’s just a handful of lines written in a different language, these tags can be applied just to those lines.

Next Section: Working with Schemas