Skip to main content

Dynamic Table of Contexts

The Dynamic Table of Contexts (DToC) is a standalone tool within the LEAF Commons suite that supports creation and curation of encoded text editions. DToC can also be used in conjunction with LEAF-Writer.

DToC is an in-browser e-reader that uses the underlying structure of an encoded XML document to allow different paths through the text to be discovered when read. The text, or collection of texts, can be navigated via semantic tags (like people and places), the document structure (like essays or chapters), or an index. DToC also allows readers to 'curate' the text they are reading based on the editor's tagging.

Fundamentals​

A complete DToC has three components: a semantically-tagged, TEI compliant XML document, an index stored in an XML document, and a JSON file which informs DToC how to present your document. The index can be stored within the primary XML document, and your DToC can also be comprised of multiple XML documents.

DToC requires that the text file must be hosted online in .xml format. GitHub, GitLab, or other public-facing online hosting services will work for this purpose.

The JSON file can be managed within the tool itself, or uploaded from your desktop or from the cloud.

The optional index file must also be hosted online.

note

If you have a GitHub account you can sign in and access documents stored in the cloud, as well as locally stored documents on your own device. Being signed into GitHub also gives you more saving options.

The JSON file is the backbone of the DToC edition. You can use the built-in configuration tool or build your own using the sample available here. When you "save" a DToC you are actually saving or updating the JSON file.

To build and curate a DToC you will need some familiarity with XPath syntax. Primarily you will be working with node (element) and attribute selection within a document, and DToC provides some basic templates for how you can use XPath. There are some examples peppered within this documentation and the tutorials.

Once opened, the DToC interface has three panels.

Tags Panel​

The left panel by default shows Tags (the tags input from the curated markup field). If you include an index file, you will be able to toggle between Tags and Index (the inputted index of terms). Creating an index for DToC will be outlined below in the "Creating an Index" section.

The “Tags” tab displays any of the tags found in your XML document. The numbers next to the tags display how many times the tag appears in the document. Clicking on a particular tag shows where words encoded with that element appear in the document. The Table of Contents in the center panel expands, presenting the location of the selected term in each section of the text in blue; the Document Model highlights the lines that contain the term in the corpus, and the Reading Pane highlights the selected term in the readable text.

To reset any search or filter option select the “Clear” button located at the top of the Document Model.

If you are working with a text in multiple sections, you can limit your search to a specific section by choosing “Filter by Chapter.” Clicking on the “Filter by Chapter” button yields a drop down list of the available sections. Once a particular chapter or section has been selected, the index terms will automatically be narrowed down.

Table of Contents Panel​

The center panel is the Table of Contents. If you are working with a multi-section document the Table of Contents presents the section breakdown in this panel. Each section is represented by the title(s) and author(s) specified in your XML document. Clicking on one of the sections or chapters will bring the text of the selected section into the Reading Pane.

The Table of Contents also contains a search function. The search box is auto-complete enabled, but it does not recognize partial matches, that is to say, typing in the first few letters of a word and pressing enter will not provide a recognizable search term. You may, however, search for partial words by adding an asterisk at the end of the string of characters you have entered. Once a search is conducted, the different sections, or chapters, that contain the searched term will appear in the Table of Contents with brief excerpts of text surrounding the term in question. Lines in the document model, the narrow column to the right of the Table of Contents, will become highlighted to represent the location(s) of the term in the corpus. These highlighted lines may be clicked to bring the corresponding text into the Reader Pane. To search for a new term, delete your word in the “Word Search” box, or click on the “Clear” button located at the top of the document model, then type in or select a new term.

Reading Pane​

The right-hand panel is the Reading Pane. The text in the Reading Pane is presented as a single block of text.

If you've separated or compiled the text into sections (chapters, essays, poems, etc.) the Reading Pane will load the individual sections; the entire document will not appear unless no text divisions have been embedded into the document.

Creating a DToC Edition​

On the DToC homepage, you will see several options for opening a DToC (From the Cloud, From URL, From Your Device, Paste, New). To create your first DToC choose "New". This will open an Input Configuration Panel to input the information needed to create the DToC.

There are five areas of information on the Configuation Panel:

  • Metadata
  • Documents
  • Parts
  • Formatting
  • Curation

Some information is required, and some is good to have. Required information is indicated below.

Configuration Fields​

DToC Edition Metadata​

Creates a title for your full edition. This will appear at the top of your DToC. Adding a subtitle is optional.

Documents​

(Required) Paste the URL of your encoded document in the space provided. If you are creating a DToC from multiple files, or are including an index file, separate URLs with a comma. If you are using a XML file hosted on a GitHub or GitLab repo, make sure that you are using the URL for the "raw" file.

Corpus Parts​

These instructions create the navigation mechanism for the DToC.

  • Corpus Part: (Required) This points to the node within your encoded text that will be the body of your DToC. Make sure you are using a div element, and give it a descriptive @type attribute (e.g., chapter, essay, story, poem, etc.) You'll need to make sure that you are using the correct attribute from the XML file(s), and that if there are multiple sections they are all using the same @type value. The XPath syntax required is //div[@type="chapter"] (chapter here is just for example).
  • Part Content: Use this field if the text of each document part that you want to display is separate from the entirety of the document part.
  • Part Title: (Required) This displays the text that will appear in the Table of Contents panel (it is the title for a section of the text). For a simple DToC use head in this field.
  • Part Author: This displays the author of each part of the DToC (e.g., if your DToC includes multiple essays by different authors, and they are tagged with the docAuthor or byline element, their names will appear below the Part Title in the Table of Contents.)
  • Corpus Index: This field is only used when you are including an Index in your DToC.

Formatting​

These instructions are optional, and of value only if your edition includes images, links to other places on the web, and/or involves styled notes.

Curation​

By default if you leave this field blank DToC will automatically create a basic curation from your identified div. This will be addressed in detail below in the "Curating Your DToC" section.

Click "Done". Your basic structured DToC should appear in the interface.

note

The required fields for a DToC JSON file are the same regardless of whether the JSON is created elsewhere or generated via the Input Configuration Field. If uploading a DToC via JSON file, it is recommended to use this template.

Curating Your DToC Edition​

The real value of the DToC lies in curating it based on the semantic and structural encoding you've done in your document. There are three ways to curate the DToC: Easy, Moderately Complicated, and Challenging. We'll break them down here.

Easy Curation​

From within your DToC click on the "Curate Tags" button at the top right. The Tags panel now becomes an editor.

Click the "+Add" button. In the new row you should see a dropdown menu that offers all of the tags that are available for curation. Choose one of the elements. Make sure to add two forward slashes (//) before the element name, so that you see (e.g.)//persName. In the label field type a human-readable label like "people".

Click the "Show" button -- you'll see where that tag appears throughout the document.

Continue to add (or remove) tags as you wish. When you have completed (or even if you want to see partway through your curation what it looks like), click "Done Curation" at the top right. You should now be able to see all of the labeled elements with a count of how many times each tag appears throughout the text.

If you're curious (and you should be!) choose the "Edit" option from the top left dropdown menu. You're back in the Configuration Panel. If you look at the Markup field at the bottom of the screen, you should see all of the tags you've curated in JSON format.

Moderately Complicated Curation​

To add a number of elements and to distinguish between elements using attribute values, use the Configuration Panel. From within your DToC choose "Edit" from the dropdown menu in the top left. The tags you've already curated should appear in the Markup field. There are two key components: the XPath and the Label. This pair is wrapped in curly brackets within square brackets like this [{"xpath":"//div","label":"div"}]. You can add additional elements by following these steps:

  1. Put a comma between the closing curly bracket and the closing square bracket. Click return.
  2. On the new line create a new pair with the same structure, such as {xpath:"//placeName","label":"places"}. You can add as many pairs as you'd like -- just be sure that you continue to add a comma between the new pairs and place the end square bracket after your last pair.
  3. When you've finished, click Done. You'll be returned to the DToC, and should see the additional elements with labels in the Tags panel.

If you do not see them, it means that there was an error in your JSON syntax. The Configuration Panel does not save information that includes errors, so you will have to go back and recreate them. It is always a good idea to copy-paste and store your work in a simple text editor on your desktop to help you troubleshoot and avoid losing the work you've done.

Challenging Curation​

DToC allows you to draw upon more granular forms of encoding using attribute values. If you want to distinguish among groups of people, places, objects, etc. and you have captured those distinctions in your markup, you can do that using the XPath-label pairings in JSON. You do have the option to do this work in the DToC environment or the Configuration Panel, but it is probably easiest to work in an external editor building a JSON file, and then upload to DToC. The challenge is to keep track of the attribute values you've encoded, as well as the XPath syntax. If you have used the @type, @subtype, @role, @key, etc., you can break them down such that:

{xpath:"//persName[@key="potter","label":"Harry Potter"]},
{xpath:"//placeName[@type="school","label":"Hogwarts"]},
{xpath:"//objectName[@subtype="uniform":"label":"robes"]}]

If you want to save this particular curation, download the JSON file and upload it later using the "Open" option on the DToC home page. Your DToC will open in the state that you saved. You can create as many curations as you wish for any given text.

Creating an Index​

The Index feature of DToC provides a different way to navigate your texts -- similar to the indexes in printed books, providing a categorical list of names, subjects, concepts, etc. along with accessible references to where they appear in the text. The Table of Contents in the center panel expands, presenting the location of the selected term in each section of the text in orange; the Document Model highlights the lines that contain the term in the corpus, and the Reading Pane highlights the selected term in the readable text.

In order to create an index for your DToC it is best to create a separate index file in a TEI-XML document (which must be hosted online, ideally in the same place where your document file is hosted). It should by default be labeled 'index.xml'. Make sure that the index file includes <div type="index">

The index file is structured as a nested list of items (and then lists of sub-items within that list) that provides a robust keyword catalogue of your text(s). all items in your index are invoked by means of unique identifiers, which are created by adding the @xml:id attribute to every tagged word or phrase that you want to include. If there are multiple references to an individual entity, then each reference needs to have its own unique identifier. If you haven't already created this structure in your encoded document you'll need to go back and do that work now. The good news is that you can continue to refine and add to your index, making sure that you have captured all of the references that are valuable to your DToC. To help you get started, we've created a template that you can build from here.

!! Don't forget: once you've published your index file online, you'll need to grab the URL for the file, go back to the DToC Configuration Panel, and add it in the Documents panel after the other URLs (with a comma in between). Under Corpus Parts you'll then need to add //div[@type='index']

DToC and LEAF-Writer​

A great way to build and enhance your DToC is to work in tandem with LEAF-Writer -- when you host your files in a GitHub repository you can work on your document, index, and JSON files together: log into your account in LEAF-Writer in one browser tab, DToC in a second, and GitHub's simple editor in a third. You can then move back and forth between your encoded document and the DToC to enrich your curation and add to your index!

note

For more on creating your first DToC, see DToC Step by Step guide.