textbender

Textbender Demonstration

Textbender is a system of collaborative writing based on recombinant text. It implements a Web-based medium of distributed composition with an underpinning in evolutionary genetics. Textbender is aimed at creative works, particularly at short verse and prose. This demonstration begins with a quick preview of the latest alpha version, followed by set-up instructions. The main part is a walk-through of the collaborative process, from editing to publication.
Preview  Set-Up
Walk-Through: 1.Editing 2.Transfer 3.Publication
Demo Wrap-Up  Follow-Up  Notes

The text exists as a population of variants, one per author.

The population is made up of documents posted at various locations on the Web. All documents are related, either by common origin or by cross-transfer. Each is the working copy of a single author, who has independent creative and editorial freedom.
two browser windows, each with several lines of text highlighted in graded colour
Figure 1. Two variants of a poem.7 One is from a Web page (left), in which the user has selected a range of lines. In response, the corresponding lines of the user's working document (right) are automatically marked. Text sources: www.emilydickinson.org/safe/.

Recombinant text is basically XHTML, with a few additions. It may be edited much like an ordinary Web page. The main editing tool is your text editor, with occaisional help from a special formatter. Editing will be demonstrated in the first stage of the walk-through.

Authors swap fragments and arrangements of text, peer to peer.

Fragment transfer is copy and paste, but with a few differences. One difference is genetic alignment. It enables transfer chromography, a graphical rendering of both source and target that reveals patterns of similarity, and helps to guide each transfer.
editor window showing portion of document source, with selected region highlighted
Figure 2. The user's working document in a text editor. The region was manually selected by the user, aided by the visual cues of the browser (figure 1, right).

Another difference is that sources are automatically acknowledged, with each transfer. Transfers will be demonstrated in the second stage of the walk-through.

Genes encode a traceable record of authorship, throughout.

Despite all the copying back and forth as the population evolves, the system remembers the authorship of each contribution, no matter how small, wherever it happens to survive in an individual document. A document is a patchwork of discrete genes, each of which encodes a piece of text. In addition, each gene records its own origins and ancestry. The combined ancestries of all genes of a document are, therefore, a record of that document's authorship. When a piece of text is transferred to another document, a portion of authorship is transferred too. When that document is later subject to a genealogical trace, it will reveal the contributions made to it by all surviving pieces of text, and the historical authorship of each.
editor window showing same portion, but with region replaced
Figure 3. The document after pasting. The pasted text (final four lines) is from the Web page (figure 1, left). It includes traceable source attribution, yet the procedure is no more difficult than plain-text copy and paste.3

In practical terms, the significance of genetic encoding is that, when an author publishes her latest work to the Web, she hopes others will recognize its best parts, and copy them to their own documents. To the extent that they do, she gains an increased ‘share’ of those documents as a contributing author. As well, she gains additional published sources from which her contribution/share might grow further, spreading to other documents of the population. Authorship and publication will be covered in the third stage of the walk-through.

Note: Textbender and the medium of recombinant text are both in the early stages of development. This an alpha version of textbender, primarily for design review by test artists. Depending on their feedback and advice, the first beta version might be similar to this, or it might be quite different.

If you encounter problems running the demo, or if you have questions about it, please follow the reporting guidelines at page bottom.

Set-Up

Before beginning the walk-through, there is some intial set-up. It includes starting and testing the software, and obtaining a working document.

The software starts from the browser. It requires that Java and JavaScript be enabled in the browser. Not all browsers are tested yet. Here are the latest test results:

OS/browser platforms, and test results.
platform ok details
Linux Firefox ok
Linux Mozilla ok
Windows Firefox no Transfer failed with anonymous JSExceptions. A second attempt succeeded. But then reload attempts failed (with the same exceptions), until the browser was restarted. We'll fix this...
Windows IE IE7 is not supported. Unfortunately, it does not comply with Web standards (XHTML and DOM) that textbender depends on.

To start the main part of the software, click on: http://zelea.com/var/cache/textbender-demo/textbender.a.r.desk.jnlp.

Or, if your browser fails to jump into action, but you have Java installed, then the browser needs to learn to associate a ‘.jnlp’ file with the ‘javaws’ (Java Web Start) launcher. Please see the instructions on ‘.jnlp’ association at: http://mindprod.com/jgloss/javawebstart.html.

Or, ensure that Java 6 is installed; then enter this on the command line:

javaws http://zelea.com/var/cache/textbender-demo/textbender.a.r.desk.jnlp
On first launch, it asks for permission. Then it runs in the background, separate from the browser. (It places no window on your desktop.)

Testing the Software

To test the software, load a page of recombinant text, such as this one: text/amoretti-epithalamion.a.75/spenser/text.xht.

on left, browser showing poem; on right, same but with user-selected text, and applets
Before and after activation. Before (left), the page looks and functions like an ordinary Web page. Activation occurs when some text is selected (right). A boot applet appears (top right), and a toolbar applet (top). Then the selected text is chromographed. Text source: etext.virginia.edu.

When you select some text, the in-browser software should activate. A toolbar applet and a chromograph should appear, as shown above.

Obtaining a Working Document

The easiest way to obtain a working document is to copy one. Sources may be found on the Web by searching for the signature keywords: ‘textbender_’ and ‘_mark’:

http://www.google.ca/search?q=textbender_+_mark&filter=0

The above search will list all sources that exist, more-or-less. The list is short, but it should include a few poems, such as this one:

text/amoretti-epithalamion.a.75/j/text-01.xht

Choose one of the poems, and copy its source code to a file. The simplest way to do this (without having to worry about Unix vs. Windows line-endings, and loaded vs. source code) is to:

  1. View Page Source, in the browser.
  2. Copy the source to the clipboard.
  3. Paste it into a new file with a ‘.xht’ or ‘.xhtml’ extension. (The extension matters because it cues the browser to parse the content as XHTML, and the software depends on this.)

Then load the newly created file into the browser.

browser window showing the copied poem, and a toolbar applet at top
On loading of a working file, the in-browser software activates immediately. Text source: www.heracliteanfire.net.

Another step is needed to turn this file into a proper working document. But first, there is a minor test to perform.

Testing the Undo/Redo Facility

  1. Pop the menu from the toolbar applet,2 and press Test Modify.

    A change is inserted in the text, near the top.

  2. Press Back, on the browser's main toolbar: the change is undone.
  3. Press Forward: the change is redone.

    That is how it works. Normally you will work on the document in an editor. But sometimes you need to modify it in the browser. In that case, the changes are stored as separate files. The undo/redo facility allows you to navigate among them, back and forth.

Branching a New Revision Line

Every author's working document must be assigned a unique revision line of its own. For this purpose, a branching tool is provided.

  1. Press Back, if necessary, to undo any changes of the previous test.
  2. Pop the menu,2 and select Branch Revision Line.

    Note that it reloads a new page. The new page is identical, except in its encoded meta-data.

  3. Press Save on the toolbar applet.

    The working document is now formally yours.4

That completes the intial set-up. What follows is a walk-through of the routine process of composition, divided among three stages: editing, transfer and publication.

1. Editing

This stage will demonstrate how to edit a working document with an ordinary text editor. A special formatter is also needed on occaision, and we demonstrate that too.

Load the working file into a text editor. Any editor is OK.

editor window showing top portion of document source
A working document in a text editor. This particular editor has custom syntax highlighting that renders genetic markup in a faded grey.1 Text source: www.heracliteanfire.net.

The markup language is Recombinant XHTML. One obvious difference from ordinary XHTML is that each line is preceded by a separate tag (the grey ‘div’ tags in the left margin of the screen shot, above). These tagged lines are leaf genes. Leaf genes are small genes at the structural ends of the gene tree. They have two important properties that bear on editing. They:

The information includes the origins of that piece of text, its ancestry, transfer locus, and other genetic meta-data important for transfer and publication. The gene is a link that associates that information and that piece of text. What is important during editing is to maintain that association, and avoid breaking the link. The rule of editing is:

Never Orphan a Piece of Text from its Leaf Gene

You can change anything, provided no piece of text ends up as an orphan, separate from its parental leaf-gene tags. Deleting text is safe. Inserting new text is safe. But caution is needed when moving or copying it. When moving or copying, effectively treat the whole gene as a single unit.

                <p t:g="l">
<div t:g="6">       Except for you. Sly time cannot devise </div>
<div t:g="5">       you fade in tar nor water green your name. </div>
<div t:g="4">       Poems hold where bodies compromise. </div>
<div t:g="3">       And if the heavens hate your heathen fame, </div>
<div t:g="2">       let them send some fat reaper to subdue </div>
<div t:g="1">       your blood but miss the sparking flint of you. </div>
                    </p>

For example, consider the working text above. The writer edits it, to obtain the result below. He moves some pieces (orange) to different locations. In one place, he cuts the top line of the stanza and pastes it to a new stanza, while deleting part of it (red). Note that he did not simply cut the phrase “Except for you”, because that would have orphaned it from its leaf gene; instead he cut the entire leaf gene, and moved it as a unit.

                <p>
<div t:g="6">       Except for you. Sly time cannot devise </div>
                    </p>
                <p t:g="l">
<div t:g="5">       Neither tar will fade, nor water green your name. </div>
<div t:g="4">       Poems hold where bodies compromise. </div>
<div t:g="3">       And if the heavens hate your heathen fame, </div>
<div t:g="2">       let them send some fat reaper to subdue your blood. </div>
                    If they do, they'll find they've claimed a trophy tag
<div t:g="1">       but missed the sparking flint of you. </div>
                    </p>

In another place, he cuts the phrase “your blood”, and pastes it to a different line. Technically, he has broken the rule, because “your blood” is now orphaned from its parental leaf (bottom line). However, it is only two words, and the user judged it insignificant. So this is an exception to the rule.

In other places, he inserts new text (above, blue). He does not bother about leaf genes while inserting new text. In particular, he does not create gene tags, nor any other genetic markup. As a consequence, the document is no longer in proper format. At some point, eventually, the document will need to be reformatted. When reformatted, it would look something like this:

                <p t:g="v">
<div t:g="6">       Except for you. </div>
                    </p>
                <p t:g="l">
<div t:g="5">       Neither tar will fade, nor water green your name. </div>
<div t:g="4">       Poems hold where bodies compromise. </div>
<div t:g="3">       And if the heavens hate your heathen fame, </div>
<div t:g="2">       let them send some fat reaper to subdue your blood. </div>
<div t:g="w">       If they do, they'll find they've claimed a trophy tag </div>
<div t:g="1">       but missed the sparking flint of you. </div>
                    </p>

Using the Browser to Reformat a Document

To reformat:

  1. Save the document from the editor, to the file.
  2. If it is not already in the browser, load it.
  3. Press Reload on the toolbar applet.

    The document is then reloaded, reformatted, and displayed as a new page.

  4. Save it from the browser back to the file. (Press Save on the toolbar applet.)

At this point, you could publish the reformatted document. Or you could run other tools on it. Or, you could reload it into the editor,5 and continue editing. You would then see the new genetic markup, as shown above.

Patterns for Editing Leaf Genes

The formatter can recognize various ‘shorthand’ editing patterns, that together cover all the things you might want to do to a leaf gene. You can duplicate leaf genes; break them into multiple lines; join them together; or nest them one inside the other; and various combinations of these — and all of this may be accomplised in intuitive ways, using the text editor.

Most of these short-hand patterns are not yet coded. When they are, they will be listed here in a schematic outline. And that will end the editing stage of the walk-through. Further details will be provided by the user manual of the primary formatter, genetic encoder.

2. Transfer

This stage will demonstrate how to selectively merge another author's work into your own, by paired-regions transfer. In this method of transfer, you choose a source document from the population; select a region of its text; and paste it into your own document.

Your transfer source might be a familiar collaborator; or the original author who got you interested in that particular text; or someone new who has posted useful work to the Web. Or you might be an editor who receives formal contributions from writers; or maybe a compiler who collects and assembles pieces for a larger work. In any case, from time to time, you may need to search the population for source texts, and this is where we begin.

http://www.google.ca/search?q=+%22textbender_+Amoretti+and+Epithalamion+A75+_mark%22&filter=0

The above search will list the entire population of the text identified by the textbendermark of ‘Amoretti and Epithalamion A75’7. The population is small, so there are not many variants to choose from. But suppose that you choose this one:

text/amoretti-epithalamion.a.75/carter/text.xht

Open that page, plus your working document (side by side, in two browser windows), as shown below.

two browser windows, each with several lines of text highlighted in graded colour
A transfer source (left), and a working document (right). On the left, the user has selected a region of text. In response, the corresponding lines of the working document are marked (right). Text sources: www.heracliteanfire.net.

Select a region of text in the source. The the in-browser software will activate, and a chromograph will appear on the selected lines.6 The same lines will be copied to the clipboard too, in genetic format. (Do not press Ctrl-C or anything, or you'll clobber them with a plain text copy.)

A second chromograph marks the corresponding lines of the target (above right). Use it as a manual alignment guide in the editor; either to select the same region (as shown below), or to position the cursor at a convenient insertion point.

editor window showing portion of document source, with selected region highlighted
The working document in a text editor. The user has selected a region of text, aided by the visual cues of the browser (further above, right).
editor window showing same portion, but with region replaced
The working document after pasting. The region has been overwritten by a copy of the text from the source browser (further above, left).

Clipboard transfers are conveyed as ‘clip-genes’. A clip-gene is distinguished by having a ‘t:c’ attribute, instead of the usual ‘t:g’. It is a stub that serves as a placeholder for a full gene. When the working documented is next reformatted, each clip-gene stub will be replaced by a full gene, complete with ancestry and authorship data. Meantime, for editing purposes, clip-genes are treated just like ordinary genes.

editor window showing same portion, but t:c attributes are now t:g
The same document after eventual reformatting, e.g. prior to publication. Reloaded into the editor (‘reverted’ in Emacs-speak), you can see that the reformatter has translated the pasted text from clip-gene to proper format. At the same time, it has appended the text's ancestry and authorship meta-data to the document tail (not shown).

Follow-Up Editing and Transfers

Proper merging of the transferred text may entail follow-up editing and micro-transfers. The software to support this is not yet ready.

Often, overwritten pieces of text will need to be restored to their former state, at least in part. The former state is still visible in the target browser (further above, right). This section will demonstrate how to use that browser as a source, in turn, for the back-transfer and in-line merging of small text fragements. It will also demonstrate ad-hoc source attribution, by a similar technique.

3. Publication

This stage will deal with publication, plus attendant issues of authorship and ownership. It is not fully documented, yet...

There are two modes of publication: peer publication and end publication.

Peer Publication

In peer publication, a writer's working document is made available to other writers for the purpose of collaborative composition. Mostly this means posting your working document to a Web site (any site will do). In addition, for first postings, a simple news/listing service will be provided; so new documents can announce themselves to the population.

A facility will be provided to gauge, rank and analyze an author's literary contributions. This will provide feedback on the author's publications. A central server will scan the wild population, and provide a Web service to answer queries, such as:

End Publication

In end publication, an editor's working document is redacted and published in a mainstream, mass medium, such as print. The purpose of end publication is to serve a wider readership. This section (when ready) will discuss matters such as commercial licensing and royalty payments; how these might be handled for recombinant texts. It will also outline specialized tools in support of editors and publishers, particularly for authorship/ancestry tracing.

Demo Wrap-Up

On Windows, the in-browser software leaves temporary files on the desktop. After closing the browser, you can delete them.

The desktop software is safe to leave running. It will stop when the desktop shuts down. If you prefer, you can stop it sooner by locating the process named ‘java’ or ‘javaws’, and sending it an interrupt signal.

Follow-Up

If you have questions about the demo, or you wish to report a bug, or discuss issues with developers, and so forth, please visit the maintainer's task page. It details the current development priorities, and provides links to the discussion group.

Or, if you wish to consider participating in other ways, please visit the contributor's page.

Or, for other information, please visit our home page.

Notes

1.

The editor is Emacs. Its custom font locks (or syntax highlighting) are specified in the following configuration files: http://zelea.com/.emacs; http://zelea.com/system/host/obsidian/usr/local/share/emacs/site-lisp/sgml-mode.el; and http://zelea.com/_/Xresources-light.txt.

A darker window is better for coloured fonts, though. The configuration for that is here: http://zelea.com/_/Xresources-dark.txt.

2.

There are two ways to summon the in-browser popup menu. The easiest way is to click the mouse (using any button) on the background of the toolbar applet, at page top. This works with remote pages, as well as local. Not all actions are enabled, though, when the menu is popped in this way.

Another way is to Ctrl-click the mouse inside of the page text. This method only works with local pages. It has the side effect of selecting a single leaf gene (e.g. a line), which then becomes a target for certain actions, selectable from the menu. (On a slow machine [tinman windows], it may take repeated clicks to pop the menu. Try releasing the control key, immediately after pressing it.) [FIX might be: prevent flooding by key events, as apparently occurs on Windows.]

3.

The transfer took three gestures: in-browser selection of the source text, in-editor selection of the target, and finally paste. Ordinary copy and paste would have required, in addition, an in-browser copy gesture. That step is eliminated by textbender's in-browser tools. If a target-lock tool were added to the editor, it could further streamline the procedure by automating step 2, in some cases.

Authorship/ancestry data was not transferred here, only pointers to it. The actual data will follow when the document is next reformatted, e.g. prior to its next posting, for peer publication.

4.

Without this step, although you could work on the document, you would gain no credit for it. Your modifications would either go unattributed, or would be credited to the previous owner of the document, from whom you copied it.

5.

This is inconvenient, for sure. All that saving and loading, back and forth, is necessary because both editor and browser are modifying the same document. Fortunately, the in-browser modifications are infrequent. And if the editor is customizeable, it can usually do the job itself. For example, reformatting: just program the editor to save the file; run the genetic encoder on it; and reload. The hardest part would be to handle any error output, and display it to the user.

6.

The source chromograph may be partly obscured by the browser's own selection marks. Click to clear the marks away, and leave the chromograph unobscured. (This needs to be automated, eventually.)

7.

Two populations are shown in this demonstration. Both are hand-assembled, laboratory affairs, and neither is quite typical of a recombinant text. The population in the preview comes from text/safe-in-their-alabaster/. It is actually the work of a single author (Dickinson), and some liberties were taken in transcribing it. Also, the genetic alignment between the two variants shown in the preview is questionable, and unintuitive. A better example population is needed for this.

The population in the rest of the demo is from text/amoretti-epithalamion.a.75/. It was hand-constructed from the historical archives of a Wiki. In many ways, a Wiki is the closest thing to a recombinant text. Although it lacks a true population, it has a linear record of variants in its historical archive, and these can be extracted to construct a population, to a limited extent. Unfortunately, suitable Wikis are hard to find. They are not popular for verse composition, and the Wiki used to construct this demo population has since closed.

At some point, alpha testing will generate real populations. Then we'll have better examples to present.

maintainer Michael Allan
textbender

Portions of this document were contributed in 2007 to the Wikipedia article on recombinant text.

Copyright 2007, Michael Allan. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Textbender Software"), to deal in the Textbender Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Textbender Software, and to permit persons to whom the Textbender Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Textbender Software. THE TEXTBENDER SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE TEXTBENDER SOFTWARE OR THE USE OR OTHER DEALINGS IN THE TEXTBENDER SOFTWARE.