LEAF-Writer Commons Documentation: Advanced

Accessing LEAF-Writer

You do not need to register for an account to LEAF-Writer. In order to take full advantage of LEAF-Writer's features - in particular being able to access and collaborate on documents in the cloud - you can use your GitHub account. If you don't' yet have a GitHub account you can register for one here

note

After logging in with GitHub you will need to authorize LEAF-Writer. You will only need to complete this action once.

LEAF-Writer and Privacy

You can choose how much information Privacy settings can be accessed before or after opening a document via the identity button in the top right corner. These settings contain the full Privacy Policy and allow you to customize your cookies consent preferences. Strictly necessary cookies, without which the website cannot function, cannot be disabled. Cookies related to basic interactions and functionalities can be disabled, but doing so will limit the functionalities of LEAF-Writer. Anonymized measurement cookies, which collect information about your website activity, can also be disabled.

You can change your cookies preferences at any time, but you will lose the current annotation and tagging work.

Open a Document

When you open LEAF-Writer, you will be prompted to choose a template or sample, or to open a document from the Cloud or your device.

If you would like to open a document, it must be LEAF-Writer–compatible: an XML document that is well-formed and references a schema supported by LEAF-Writer. Supported schemas include the Orlando and CWRC bespoke schemas, as well as the customizations provided by the Text Encoding Initiative (TEI).

Open a Template

There are four available templates: Blank, Letter, Poem, and Prose.

Templates come with pre-existing text. To add your own text into a template:

1. Right-click on the tag that contains the text you would like to delete.
2. Choose Remove Content Only. This action will remove the content from the tag, but will leave the tag in the document.
3. [Optional] Choose Remove All to delete the text and the tag.

For more information on tags, see the instructions for the Markup Panel.

Open From the Cloud

You can search for and load public LEAF-Writer–enabled documents or repositories from GitHub.

Upload From Your Computer

You can open a LEAF-Writer–compatible document (i.e., a document that has previously been opened in LEAF-Writer) from your computer by clicking From Your Device and dragging and dropping a file into the popup that appears.

Open XML

You can paste XML directly into the box provided (see screenshot below) to create a LEAF-Writer compatible document. If the document is not well-formed or uses a schema that is not supported by LEAF-Writer, it will not open.

Editor Modes

There are three editor modes in LEAF-Writer to support you in the way you want to tag, and what you want to do with the output of your markup. You can choose:

• Markup Only: allows you to tag in XML using a TEI or Orlando schema.
• Markup and Linking: to combine XML tags and RDF (Resource Description Framework) allows for Semantic Web annotations that are equivalent to the XML tags you create, and are consistent with the hierarchy of the XML schema so that annotations will not be allowed to overlap.
• Markup and Linking (with overlap): allows for only RDF to be created for entities; overlaps with existing XML structures.

Note that the default mode is XML + RDF when you open a document. While you can change the editor mode at any time, if you have overlapping entities in your document and switch to a mode that prohibits them, the overlapping entities will be discarded.

Save Your Work

If your document is stored in GitHub, it will save automatically in the background. There are three ways to manually save your work:

• Click Save or Save As in the top-left hamburger menu
• Click Click to Sync (cloud icon) next to the document’s title (the icon will be orange with an orange dot next to it if there are unsaved changes)
• Use a keyboard shortcut (Ctrl+S or ⌘+S)

LEAF-Writer saves to the default source of your file. For example, if you open a document from GitHub, it will save in GitHub. If you open a document from your computer, it will save to whatever repository you used to log in (GitHub).

To save changes to a repository you do not own, the repository owner needs to have added you as a collaborator from the GitHub repository settings. If you are not a collaborator on the external repository, you can still save a version of the document with the changes you have made as a new repository that you own.

Navigation Panels

There are three different tabs on the left-hand side of LEAF-Writer.

Table of Contents

The Table of Contents allows you to see and navigate through different sections in your document.

Markup Panel

The Markup Panel displays the document’s XML tags. From the Markup Panel you can add, delete, edit, and copy and paste tags in the document. Clicking on or hovering your mouse over a tag will show the full name of the tag as well as the first few words of the tag's content.

There are two ways to select a tag in the Markup Panel:

• Click the tag until it shows next to it to select the contents of the tag.
• Click the tag until it shows next to it to select both the contents of the tag and the tag itself.

For advanced users only: The Markup Panel also allows you to edit the document's header by right clicking on teiHeader, which will open the XML editor with only the elements in the document header. This feature currently has minimal functionality.

Entities Panel

The Entities Panel lets you see the entities tagged in the document. You may view the items in this tab sequentially, alphabetically, or categorically.

Hover your mouse over an entity and click Edit (pencil icon) to bring up a popup box where you can edit the attributes of an entity. Hover and click Remove (circle icon) to remove the tag.

Toolbar

LEAF-Writer has a toolbar that can be used to add, edit, and delete tags.

Icon	Action
	Displays a list of eligible tags you can add to your document.
	Opens a popup that allows you to tag a person by name.
	Opens a popup that allows you to tag a place.
	Opens a popup that allows you to tag an organization or company.
	Opens a popup that allows you to tag a title or the text of any type of work.
	Opens a popup that allows you to tag a general purpose name or referring string.
	Opens a popup that allows you to tag a citation.
	Opens a popup that allows you to tag a note or annotation.
	Opens a popup that allows you to tag a date.
	Opens a popup that allows you to tag a correction you have made to the original text.
	Opens a popup that allows you to tag a keyword.
	Opens a popup that allows you to tag a link or URL.
	Opens a popup that allows you to add a translation for the text in a div. The translation appears in a new div that is added beneath the div with the original text.
	Shows or hides XML tags in the Editing Pane.
	Opens a right sidebar that shows the document’s raw XML. This sidebar also contains the Image Viewer and Validation tabs.
	Validates the XML document against the associated schema.
	Opens the Settings Panel.
	Toggles to fullscreen view.
	Opens the LEAF-Writer Documentation in a new tab.

Settings Panel

The Settings Panel is located in the toolbar. Use the Settings Panel to:

• Modify the appearance of the interface (light mode, automatic mode, dark mode).
• Change the language (English or French).
• Change the size of the text in the Editor Area.
• Turn Autosave on or off.
• Toggle whether or not entities are shown (highlighted) in the Editor Area.
• Reorganize the priority of the entity sources (see Tag Entities for more information).
• Allow or disallow Multiselection in the Markup Panel.
• Toggle whether or not Text Nodes are shown. If this option is toggled on, you can allow Drag and Drop and toggle whether or not to show Text Nodes Content.
• Reset Dialog Warnings.

Validate

LEAF-Writer has continuous validation, which means you will not need to validate your document manually as you work. If your document becomes invaild, a list of the errors will appear in the right-hand panel under the Validation tab.

If you would like to manually validate your XML document, click Validate in the toolbar. Click an error message to highlight the error in the document. You can then correct the invalid structure and the error message will disappear.

danger

If you try to save a document that is not well-formed, a popup will appear asking you to confirm if you want to proceed. You should not save documents that are not well-formed. It is important to validate your document often and fix your errors as soon as they appear.

Right Click Menus

LEAF-Writer has two right-click menus that can be used to add, edit, and delete tags.

Editor Area Menu

Right-click the Editor Area to see a menu with nine options.

Option	Action
Add Tag	Displays a list of eligible tags you can add to your document.
Add Entity Annotation	Opens a popup that allows you to add a tag.
Edit Tag	Opens a popup that allows you to edit the attributes of a tag.
Change Tag	Opens a popup that allows you to change a tag to a different tag.
Copy Tag and Contents	Copies a tag and the text it contains.
Split Tag	Splits one tag into two.
Remove Tag	Removes a tag, but keeps the content.
Remove Content Only	Removes the content from a tag, but keeps the tag.
Remove All	Removes the tag and its content.

Markup Panel Menu

Right-click the Markup Panel to see a menu with ten options.

Option	Action
Edit Tag	Opens a popup that allows you to edit the attributes of a tag.
Change Tag	Opens a popup that allows you to change a tag to a different tag.
Copy Tag and Contents	Copies a tag and the text it contains.
Remove Tag	Removes a tag, but keeps the content.
Remove Content Only	Removes the content from a tag, but keeps the tag.
Remove All	Removes the tag and its content.
Add Tag Before	Adds a tag before the tag you have right-clicked on.
Add Tag After	Adds a tag after the tag you have right-clicked on, skipping over any nested tags within the tag.
Add Tag Around	Adds a tag that will surround the originally selected tag.
Add Tag Inside	Adds a new tag nested within the initial tag you clicked on.

The options to add or change a tag include a toggle next to the search bar (see screenshot below) that controls whether or not invalid tags are shown; by default, only valid tags are shown. This would allow you to add tags that require specific children tags in order to be valid based on the current document schema. Invalid tags will be greyed out and have an error icon next to them.

Create Structure

Copying and pasting is the quickest way to build the structure of your document:

1. Click on a tag you would like to copy in the Markup Panel so it becomes bolded and italicized.
2. Right-click the tag and select Copy Tag and Contents in the popup.
3. Select the parent tag in the Markup Panel in which you would like to paste your copied tag so it becomes bolded and italicized.
4. Right-click the parent tag and select Paste Tag in the popup. The copied tag will be pasted within the parent tag after the parent tag’s other content.

note

Once you paste a tag, it leaves your clipboard. You will have to complete the above steps every time you would like to copy and paste a tag.

danger

Copy and pasting tags can create structural problems in your document if you are not careful. Make sure to fix validation errors often when copying and pasting tags.

Add Text

Place your cursor in the Editor Area and type to add text to your document. You can also copy and paste text directly into the Editor Area:

1. Copy the information that you would like to paste. If you copy text from another XML document, all existing tags will be stripped out when the text is pasted into LEAF-Writer.
2. Activate the field you want to paste into by clicking the tag in the Markup Panel. You cannot paste into multiple fields at once.
3. Place your cursor in the highlighted area in the Editor Area.
4. Paste the text using keyboard shortcuts (Ctrl+V or ⌘+V).

The Markup Panel tags will not be affected unless you have pasted over preexisting tags.

Tag Entities

LEAF-Writer is connected to the LEAF entity system, which allows you to reconcile entities in your text. See Reconciliation.

Named entities can be searched for from within LEAF-Writer using authoritative Linked Data (LD) sources such as DBPedia, Getty ULAN, GeoNames, VIAF, and Wikidata. Each source is best suited to certain entity types:

	DBPedia	Getty ULAN	GeoNames	VIAF	Wikidata
Person	✓	✓		✓	✓
Place	✓		✓	✓	✓
Organization	✓			✓	✓
Text/Title				✓
Citation				✓

LEAF-Writer allows you to choose the sources you would like to use and order them by preference:

1. Click Settings in the Toolbar.
2. Drag to reorder the sources under Entity Lookup Sources.

note

If you are unable to find an appropriate entity using the LEAF entity system, you can manually add a URI to your document when tagging. While the URI will be added to your document, it will not be saved to the LEAF entity system.

The processes to tag a person, place, organization, text/title, referencing string, and citation are similar:

1. Highlight the text that you would like to tag.
2. Click the appropriate button in the toolbar for your entity (Tag Person, Tag Place, Tag Organization, Tag Text/Title, Tag Referencing String, or Tag Citation). A list of potential matches will appear in a popup.
3. Choose the match that corresponds to the entity you wish to tag.
4. [Optional] If none of the matches are correct, manually add a URI under Other / Manual Input.
5. Click Select.
6. Fill in the required information in the popup. The information required varies slightly depending on what type of entity you are tagging.
7. Click OK.

The processes to tag a note, date entity, correction, keyword, or link are similar:

1. Highlight the text that you would like to tag.
2. Click the appropriate button in the toolbar for your entity (Tag Note, Tag Date, Tag Correction, Tag Keyword, Tag Link).
3. Fill in the required information in the popup. The information required varies slightly depending on what type of entity you are tagging.
4. Click OK.

Read-Only Mode

Next to the identity button in the top right corner there is a drop down menu that can change the mode of the document from Editing to Viewing. In this read-only mode, a number of functionalities are blocked or hidden to prevent changes in the document, namely:

• The Editor Area will not allow any typing or editing
• The toolbar will only show the Show Tags, Toggle Fullscreen, Settings, and Documentation buttons
• The Settings Menu will only show the options to modify the appeatance of the interface, change the language, change the font size, and toggle whether or not entities are highlighted
• The bottom bar will no longer show the buttons for Editor Mode, Annotation Mode, and Schemas
• The two side panels will only show the Table of Contents, Entities, and Image Viewer tabs, hiding the Markup, Raw XML, and Validation tabs