a project by

A User Guide to Juxta Commons

Purpose of This User Manual

This manual is intended to be a simple guide to using Juxta Commons for those new to textual collation and analysis online. It covers the tasks of uploading source files to the Commons, preparing witnesses for collation, and assembling those witnesses into comparison sets for collation and sharing. It does not cover the technical aspects of the Juxta Web Service, or how to customize Juxta for your own editorial environment. If you are interested in these aspects of the project, please visit the Juxta Developer Group or contact us directly at technologies@nines.org.

Getting Started

Brief Intro to Collation

In textual criticism and bibliography, collation is the process of determining the differences between two or more texts. Scholars study variations introduced during the copying of manuscripts, or the evolution of a text as we know it from its manuscript draft versions, proofs for printing and various print editions.

Each version of the text is referred to as a witness, with the primary reading version against which all others are compared called the base witness. In a scholarly edition, the results of collation are organized into a critical apparatus.

What is Juxta?

Juxta was created by the Applied Research in 'Patacriticism group at the University of Virginia, led by Jerome McGann, and developed by Nick Laiacona of Performant Software, Duane Gran, Bethany Nowviskie and Duane Gran. The original version of Juxta (offered as a downloadable desktop client) was intended to streamline the process of collation for scholars working with digitized texts. In addition to an HTML version of the traditional critical apparatus, Juxta offered three new visualizations of the differences between a group of texts: the heat map (an overlay of the texts with differences highlighted by color), the side-by-side view (two texts visualized with lines connecting the sites of difference) and the histogram (a global view of the text illustrating the portions with the most change across versions).

Juxta Commons takes the power of desktop Juxta to the web, making it easier to add files from various sources and share your results with others. It is powered by the Juxta Web Service, an open-source API that modularizes the sequence of steps required for digital collation and offers more options for working with XML documents. NINES partnered with Performant Software once more to bring Juxta to the web, and many thanks are due to our hard-working R&D team: Andrew Stauffer, Dana Wheeles, Nick Laiacona, Kristin Jensen, Lou Foster and Susan Holland.

Adding Source Files

The first step in using Juxta Commons is adding source files to your library. Once you have an account, click on the "add source files" button at the left of your screen and choose one of three methods: upload documents from your computer, link to files online, or use the text editor to paste text from another source. Juxta can accomodate plain text, and all kinds of XML (including TEI Parallel Segmentation).

UPDATE: As of December 2012, Juxta Commons can now fully accommodate HTMl files, Microsoft Word DOCX, Open Office, EPUB and PDF. EPUB and PDF files that contain text elements (as opposed to graphics or page images) will be extracted into plain text for witness preparation and collation.

The R&D team has also added a Wikipedia API feature that allows users to link to an article on Wikipedia and select up to 10 revisions of that document. Simply put the title of the article that interests you into the blank ("Climate Change") or link to the URL itself. Choose the Link Revisions option and then browse through all revisions to select those you would like to include. After you have done so, Juxta Commons will immediately prepare those items as witnesses and begin collating them as a set. This process may take a few moments to complete, especially if the article is a long one.

Click the thumbnail image to the left to explore the options available in the sources pane of your library. These files are the building blocks of your Juxta comparisons. Once they have been added to your library, you can edit them (to remove typos or other errors that have crept into your document) or duplicate them, depending upon how you want to work with the content. Once you are satisfied with the source files you've added, the next step is to prepare them as witnesses.

Back to top

Editing Source Files

When you click on one of the sources in the list at the upper left of your screen, it will be highlighted in yellow and the contents of the file will appear in the large pane below. Any other witnesses or sets with which the source file is associated will receive a soft yellow highlight within the library to give you a quick survey of the file's usage.

From this screen you can edit your source file by clicking the text pane to place your cursor, and typing. Once you begin to work with the text, you have the choice to save the changes you have made to the document, or save them as a new source file (see screenshot). If you choose to save the changes to the document itself, Juxta Commons will remind you that your changes will potentially affect any witnesses or comparison sets created from the file. If you choose to 'Save As' a new source, you will see the familiar metadata pop-up requesting you to re-name the file and add any information you may need about the changes. Once you click 'Save As', the new source file will be added at the top of your source file list and you may continue to work on the newly created document in the central pane.

You may also download a copy of your source file from this menu at the bottom of your screen, if you have made changes you would like to preserve and share in other ways.

Back to top

Preparing Witnesses

In order to collate documents in Juxta Commons, you must first prepare your raw source files into witnesses, or versions of a single - in some cases, original - text.

In the case of plain text files, this may involve simply adding some basic metadata (title, date, source), but this step is crucial when working with XML. Once you prepare a witness from a TEI-encoded source file, you are able to share an HTML view of that witness with others, or click on the XML view to browse or edit the elements that will be included in the collation.

In most cases, there there will be one witness for every source file. However, when dealing with large files, or XML-encoded documents with extensive markup, it is possible to create multiple witnesses from one source file.

There are several ways to prepare a witness in Juxta Commons, depending upon your preferred workflow. You can click the arrow icon to the right of the filename in the Sources pane to bring up a dialog for entering some basic information to describe it, such as a title, a document author, the date of the document and any other notes that may be helpful. You also have the option of dragging the item from the source pane to the witness pane: simply click on the title and hold while dragging it. The metadata dialog will appear once the action is complete.

If you would like to streamline the preparation of your source file into a witness, or prepare several at once, you can select the relevant items by clicking the boxes to the left of the filename (see screenshot). Once you have selected the files, click on the Show Options drop-down at the upper right of the source files pane and choose Prepare Selected. Juxta Commons will take its best guess as the basic metadata for the file, which you can revise by clicking the large info button that accompanies every file on the middle navigation bar.

The Witness Pane

Once your witness has been created, its name will appear in the Witness pane and the text will show up in main visualization pane below. At this point, you have the choice of sharing the witness with your peers (to learn more, see the section on sharing, below) or preparing the rest of your witnesses and grouping them into a comparison set for collation.

If you are working with XML, you will notice that you are offered by default a "Content View" and the option of switching to an "XML View" in the header, underneath the title. Content view automatically applies an XSLT stylesheet to render the original XML file in HTML to make the text more legible. If you are working with TEI-encoded files, or Rossetti Archive Markup (RAM), the headers of the document will be stripped by default. If Juxta Commons does not recognize the schema of your XML file, it will make its best guess as to how to render it. You will then be able to switch to the XML view to further refine the output to your specifications. If you would like to explore more options for filtering the content of your XML documents for the collation, please see the section below on Advanced XML Options. Note that you can access the XSLT used to create the Content View of your witness at the upper left of the document with the other metadata.

The options available for working with witnesses in the drop-down menu at the upper right deal with grouping the witnesses into comparison sets for collation. You can select the multiple witnesses that you would like to collate and use the menu to create a set and collate them right away, or you can select one witness to add to a pre-existing set. For more information on comparison sets, see the section below.

Back to top

Creating Comparison Sets and Collating

A comparison set in Juxta Commons requires only two witnesses, but it could also be as large as twenty. Once you have your witnesses ready, you can select them by the checkboxes next to them in the Witness list and click the dropdown above. This will offer you the choice to 'Create Set with Selected' which will automatically group them and begin the collation if you choose 'Create and Collate.' If you are still working on adding files to your set, you also have the option of creating the set without collation, and deferring that action until later.

Please note that Juxta Commons was developed so that you are able to begin the collation process on a set while continuing to work on other files. If you select the collate icon next to a set at any time, you will still have access to source files and witnesses for editing and preparation purposes. However, if you choose the 'Create and Collate' option from this 'Create Set with Selected' dropdown, you will need to wait until the collation is complete to see the results and complete work on any other documents.

If you are still compiling witnesses, but want to go ahead and create your comparison set, click the 'Create Set' button and give your set a title. You will also be offered fields for entering a description about the set that will be shared with others, should you choose to make your set visible, as well as a private notes field for your own personal annotations.

You can add witnesses to an existing set by selecting them and clicking 'Add selected to set' or by clicking and dragging them over into the set under the Comparison Set pane. If you choose to add your witnesses in either of these ways, you'll need to click the collate icon to collate when you're ready. When the light is green, your set has been collated and is ready to view.

Depending upon the length of your files, the number of witnesses, or the amount of difference between them, collation could take a few minutes to complete. Once the collation status dot turns green, you will be able to click on the set and see it visualized in the pane below.

By default, Juxta Commons will collate the punctuation in your documents as well as the words. If you would like to filter out the punctuation differences, simply click on the settings icon and alter the collation preferences in the dialog that pops up. After doing so, you will need to re-collate the set to see the changes.

Back to top

About the Visualizations

The Heat Map

When the Heat Map View is selected, Juxta displays a collation of all the witnesses in the comparison set against the current base document. That base document (highlighted in blue in the witness list to the left of heat map) can be changed by clicking the title of another witness in the list. ( see screenshot).

The text is color-coded to indicate the degree of variance from the base witness evident at any particular area of the text. Lighter shades of blue indicate that fewer witnesses vary from the base text at this location. The darker the shade of blue, the more numerous the number of witnesses that differ at this location.

Clicking on the text itself reveals all variants for a particular location. The variants appear in the right-hand margin of the text as shown. There are three types of differences reported by Juxta. They are marked with the following glyphs in the witness labels:

The delta indicates a difference between base and witness text at this location.

The plus sign indicates that there is text present at this location in the witness text where there is no such text present in the base text.

Indicates that there is text present in the base text that is not present at this location in the witness text.

If you would like to investigate a highlighted variant more closely, click on the box itself, and you will be taken to a side-by-side view of the set.

When you are working with more than two documents in your comparison set, there are two more features in the witness list that may be of use to you. Depending on how much information you have entered about each witness (such as title, and date) you can click on the drop-down menu at the upper right of the list to sort the documents alphabetically or chronologically.

The 'eye' icon to the left of each witness title allows you to toggle the visibility of a particular document in your view of the heat map. For example, if you have sorted your documents chronologically, you could click the 'eye' of the later witnesses to hide them, and then step through the set to see changes appear through time. This feature is also particularly useful if you have a witness that varies greatly from your overall set. However, when you share the set, all items will be visible, by default, to others, you may want to create a new set for dissemination.

User Annotations

(Click thumbnail above to see larger image.)

There are two kinds of annotations available in Juxta Commons: basic witness annotations and regional annotations. The first, basic annotations, simply allow a user to add a note to a specific difference in the heat map, tied to the current base witness being viewed. Once an annotation of this type has been added, the pencil icon will appear next to that witness in the witness list (see explanatory screenshot) and a "User Annotations" button will appear at the upper right of the visualization. All annotations can be accessed from this button (see example).

Often when one is editing an area with significant level of variance among the witnesses, it is not that one witness the user wants to annotate, but the region of the text itself. When you click on one of these segments for which differences span multiple witnesses, Juxta Commons will group them into a larger "Witness Differences" box, with its own pencil icon. Annotations added in this box are "regional" and are tied to that area of difference even when the base witness is changed in the heat map view.

The Side-by-Side view

The side-by-side view allows the inspection of two texts at a time. By default, as you scroll through the comparison the two texts are kept in step with one another. However, if you click the lock icon at the center of the two texts, you can unlock the scrolling and explore more deeply into one document or another.

To change the texts in each column, click the 'Change' button in the corresponding column header.

The Histogram

The histogram feature is a small dialog that pops up over the heat map or side-by-side view, and allows you to step back and explore the overall rate of change across the witnesses. Longer lines indicate areas of considerable difference, while shorter lines indicate greater similarity between documents.

If you are working with extremely long documents, the histogram will offer a grey navigation bar on top of the visualization, in order to make it easy to scroll quickly through the document. This feature is particularly useful when engaged along with the heat map.

Back to top

Sharing Comparison Sets and Witnesses

The hand icon indicates that the witness or set is currently private. Clicking it allows you to share it with chosen recipients. Once the item has been shared, this icon will be replaced by a globe.

The globe icon indicates that the witness or set has already been shared. Clicking on it will bring up information about previous shares, and allow you to set up other shares, based on the visualization you prefer, or differing base witnesses. You can click on this icon as many times as you like.

When you're satisfied with a witness or comparison set, and you'd like to share it with others, use the share icons in the corresponding library panes to select your preferred method.

Sharing Methods

Witnesses can only be shared in one way: via URL. Once you click the icon to share a witness, you will be given a URL to distribute as you like. (See this example).

Comparison sets can be shared in a number of ways: URL, email, or iframe embed. An additional option is available for sharing heat map visualizations on WordPress blogs using the Juxta Commons WordPress plugin. Once you have installed the plugin on your WordPress site, one line of code is all you need to embed a comparison set within a post or page.

If you are logged into your account and working with XML, there other alternatives for accessing your files : you may download the witness from Juxta Commons as an HTML file, or view the XSLT stylesheet that generated it.

There are two steps to sharing comparison sets: first, click the hand icon and you will see a dialog that offers you two choices.

Because you have the option of sharing multiple views of your comparison set, this step allows you to decide which visualization you want recipients to see. The default state for sharing is a heat map showing the set from the beginning of the document. However, if there is a part of the comparison you would like to highlight, simply scroll to that point of interest on your screen before clicking the share icon, and then, from the dialog, choose the second option, which registers the location of the share in terms of percentage into the document (for example, "[Heat Map, 13%]").

You can choose to share a side-by-side view of two witnesses in the same way: when viewing your comparison set, click the side-by-side icon below the title (at the center of your screen) and then set the witnesses you want to showcase before clicking the share icon. You will see a dialog like the one above, except it will offer you the choice of sharing the set as a side-by-side view at the top of the documents or at a designated point therein.

Next steps: Heat Map sharing options

In the screen shot above, you can see the various options available for sharing a heat map generated by Juxta Commons. At the top, there is confirmation that the set (in this case, "Tennyson's The Lady of Shalott") has been shared, and the details of the newest share are also available (the Heat Map has been shared at "0%," or, from the top of the document, with the Base Witness of The Lady of Shalott, 1842 edition). To the right of this information are several icons: the envelope (to email the share to others), Twitter, Facebook, and a delete icon for eliminating that share altogether. As of November 1, 2012, anyone with a Twitter account can share their set by tweet, and Facebook integration is coming soon.

Beneath this information, a shared URL is available for copying and pasting links to the set, and an embed code offered for placing a small version of the set on your own site. The embed code for the set above creates the iframe below.

As you can see, the embed window offers a link to the full view of the set, as well as a button to see the list of witnesses included.

To streamline the process for those who would like to blog about their comparison sets, we have created a Juxta WordPress plugin, which will be accessible soon. Once you have installed the plugin, you can share embeds like the one above with one simple line of code.

Side-by-side sharing options

Currently, the side-by-side sharing options do not include the iframe or WordPress embed. Email and URL are still on offer, and the Juxta R&D team will continue to work on other ways to display this mode elsewhere on the web.

Back to top

Advanced Options for XML Texts

Juxta Commons can accept all forms of XML files, but has basic defaults for working with TEI-encoded files and Rossetti Archive Markup (RAM). This means that headers and other tags will be automatically excluded from witness preparation and collations, and other features (such as notes, additions and deletions) can be visualized in the Juxta Commons interface.

TEI Default Transformations

When you prepare a TEI-encoded text as a witness, Juxta Commons will automatically apply an XSLT stylesheet to render it in the Content View screen (click this link to download that stylesheet). The elements that are excluded by default are the teiHeader (as well as its child elements), and tei:front.

If you choose the XML View option, you will be able to see the XML in your file, as well as an outline on the left that lists all of the elements in your file, and provide information about how Juxta Commons handles them. You cannot edit the text of the file from this screen (to do so, you would need to view the source file and edit it there), but you can use this screen to filter the content included in your witness when you transform it (in the Content View screen) or add it to a comparison set for collation. For example, if your document has later manuscript additions or footnotes that are not relevant for the desired collation, you have the ability to disable them in bulk from the outline, or individually, by hovering your mouse over an element and choosing to include or exclude it (see screenshot).

Exceptions are made for the note and pb tags, which receive special handling from Juxta. Note content will be excluded from the main content and rendered as margin boxes in the heat map visualization. Page Break tags will be excluded from the main content and rendered as break marks in the heap map visualization, by default. There are also controls to toggle these features off and on (see screenshot) as you work.

If you do make changes to the XML elements included in your witness, you will be offered some basic file management options at the lower right of your screen. Choosing the save button will update the witness and over-write the TEI default settings. The save as button allows you to create a new witness reflecting those changes, while leaving the original witness unchanged. In this way, you could create multiple witnesses that are derived from the same raw source file, just by deciding which aspects of the content you want to be collated. There is also a discard changes button in case you want to revert the file to its default settings.

In the screenshot below, you can see a comparison set that is made up of two witnesses that were created from the same source file.

This original source file, which is a letter from the poet D.G. Rossetti to his brother, William Michael, was encoded with information about revisons that were made to the text at the time of its writing. One witness was prepared with manuscript additions excluded from the collation (thus showing the deletions only) and the other prepared with as it was encoded (complete with additions). Once they were collated, those revisions could be seen in the the heat map by toggling on the revisions (see screenshot). In this image, the blue highlights are sites of difference in the collation, with deletions appearing in red, and additions in green.

Rossetti Archive Markup (RAM) Default Transformations

If you are working with texts encoded for the Rossetti Archive project, Juxta Commons has a default very similar to that for TEI documents. The header info (or ramheader) will be filtered out of transformations and collations (unless added by the user) and the msadds element will be treated in the same way as TEI adds and dels.

Back to top

Using TEI Parallel Segmentation in Juxta

Juxta Commons is able to accept files encoded in TEI Parallel Segmentation for easy visualization of the contents, and it is also capable of outputting a TEI Parallel Segmented file based on one of your comparison sets (XML or plain text).

To upload a file already encoded in TEI Parallel Segmentation, click the Add Source button as you normally would and browse for the file on your computer. After you click 'Upload Source' the dialog will have a checkbox for you to select for Parallel Segmentation. Once you do so, and add the document to your library, the different readings will be rendered as witnesses, and a comparison set will be automatically generated for perusing the collation.

You can also generate a file encoded in TEI Parallel Segmentation from any comparison set you create in Juxta. Keep in mind, however, that this method of encoding requires that you be able to perfectly reconstruct each of the witnesses from the collation, so if you have made any changes to the settings of the collation (such as stripping out punctuation or hyphenation differences), this will affect the TEI output.

The Parallel Segmentation output feature works best when working with plain text or basic XML encoding. If you are dealing with extensive TEI markup, please note that some of your elements will not carry over into the collation output, due to the intensive nature of the operation.

Back to top

Screencast: A guided tour of Juxta Commons

Juxta Commons walkthrough from NINES on Vimeo.

NOTE: If you cannot see the above screencast, you may need to install the Flash Player from here.

Back to top

Frequently Asked Questions (FAQ)

• What is a witness?

In Juxta Commons, a witness is a document that has been prepared for collation in a comparison set. While you can filter the content of an XML witness, it cannot be edited or revised like raw source files.

• What type of files can I use?

We are continually adding new file types to Juxta Commons. As of December 2012, we accept TXT, XML, HTML and PDF. Please note that PDF files will be extracted into plain text. See the section on adding source files.

• How many files can there be in a comparison set?

The maximum number of witnesses in a given set is 15. Please keep in mind that the more witnesses in a set, the longer it will take to collate. File size is also capped at 1MB. If you encounter difficulties working with larger sets, please contact the development team using the feedback button, or by writing to us at technologies at nines dot org.

• Does Juxta pay attention to punctuation or capitalization?

By default, Juxta Commons does collate differences in punctuation and capitalization. These settings can be changed, however by clicking on the blue gearshift icon at the right of your comparison set in the list at the upper right.

Back to top

Thanks for using Juxta and happy collating!