Balisage Paper: A Wonderful Historie of Intertextual Networks: Or, How Not to Index Your Data

Intertextual gestures in Women Writers Online

In October 2016, the WWP set out to explore intertextuality as found within the Women Writers Online (WWO) corpus. WWO is a collection of over 400 works by women: originally published before 1850, now encoded in TEI and published online for subscribing institutions. In a grant proposal to the National Endowment for the Humanities, WWP staff reasoned that the breadth and complexity of the existing WWO markup would allow us to work towards a much clearer and more textured picture of the rhetoric of intertextuality: what female authors read, what they felt it important to quote, paraphrase, or cite, and what other subtler mechanisms of allusion or unintentional echo were at work that connect their writing to that of other authors.^[1]

Soon enough, a team of the WWP’s encoders and staff^[2] examined, researched, and refined a great deal of rich, dense bibliographic and intertextual data. Much later, in 2022, the WWP prepared to release a web interface for exploring this data — Women Writers: Intertextual Networks (WWIN). The WWP’s goal was to create an interface which would let people view aggregated trends in intertextuality throughout Women Writers Online, but which would also let them drill down to interesting facets.

All together, WWIN melds data from:

The first source is the TEI bibliography, a large document comprising all identifiable works which have been referenced in WWO.^[3] These works have been identified through research, and recorded in TEI <biblStruct>s. Besides information about each work’s first known publication, the WWP team also classified entries by topic or genre, using the @ana attribute. Figure 1 is a simplified example of one such entry.

                        
<biblStruct xml:id="IT03823" corresp="#frbr.work" ana="#novel">
  <monogr corresp="#frbr.expression">
    <respStmt>
      <resp>translator</resp>
      <persName gender="unknown" ref="p:pporter.xem">Porter, P.</persName>
    </respStmt>
    <author>
      <persName gender="female" ref="p:mdelave.ksv">de La Fayette, Madame 
        (Marie-Madeleine Pioche de la Vergne)</persName>
    </author>
    <title type="display">Zayde: A Spanish History or Romance</title>
    <title type="full">Zayde: A Spanish History or Romance</title>
    <title type="alt" xml:lang="fr">Zayde: Histoire Espagnole</title>
    <imprint corresp="#frbr.manifestation">
      <pubPlace>
        <placeName>London, England</placeName>
      </pubPlace>
      <date when="1678">1678</date>
    </imprint>
  </monogr>
  <note type="public" subtype="general">At the time of publication, the 
    authorship of "Zaïde" was attributed to Jean Renaud de Segrais; however, current 
    scholarship accepts Madame de La Fayette as the author, with possible assistance 
    from Segrais.</note>
</biblStruct>

WWIN can, and does, provide a web page for each bibliography entry. However, the goal of the interface was to allow exploration at scale, which is where the index page shines. The Bibliography is a paginated index of all bibliography entries, reduced to tabular form. Next to the table is a sidebar which lists out the top facets for a number of categories, such as the publication location and whether a work has a contributor of a given gender. Using these facets, one can start to perceive contours of the dataset, and one also narrow the result set to only those bibliography entries matching some criterion.

Figure 2: WWIN Bibliography index, filtered

By default, the Bibliography is sorted so that the most referenced entries appear first. This information is not part of the TEI bibliography; rather, the WWIN application compiles totals by counting references in the WWO markup. In WWO documents, intertextuality is marked by <title>s, <rs type="title">s, <quote>s, and <bibl>s.

                        
<p><!-- [...] -->The interesting ro­-
<lb/>mance of <title rend="case(smallcaps)" ref="b:IT03823" xml:id="t072"
  ><persName>Zaïde</persName></title> also, and some other
<lb/><rs type="properAdjective">Turkish</rs> tales, shewed her how frequent
<lb/>were such transformations; her romantic
<lb/>mind told her how probable were such ad-­
<lb/>ventures <!-- [...] --></p>

Each intertextual gesture tagged in WWO has some obvious metadata attached to it: an identifier, one or more pointers, element name and type. One can process the element itself to generate HTML or plain text representations of the gesture’s textual contents. However, there is additional complexity because each gesture also carries contextual information inferrable from the TEI document around it.

In Figure 3, for instance, the WWIN classifies this gesture as a title — if the gesture appeared in an <advertisement> instead of running prose, it would be classified as an advertisement instead. From the @xml:lang on the outermost element <TEI>, WWIN understands that the textual content of this gesture is in English. And, from the lack of an @author attribute on any of the element’s ancestors, WWIN can infer that the primary author of the WWO text, Sarah Green, made this particular intertextual gesture. See the appendix section “Intertextual gestures” for more information on intertextual encoding.

All in all, each intertextual gesture comprises a wealth of information about its context, as well as whatever can be gleaned from each of the bibliography entries associated with it. The WWIN Intertextual Gestures index is similar to the Bibliography index in that it takes the form of a table alongside a list of actionable facets. In this case, however, the column-heavy table of the Bibliography has been replaced with a table which reduces the amount of bibliographic data. The resulting table attempts to make clear the relationship between each gesture, its source WWO text, and its referenced works.

Figure 4: WWIN Intertextual Gestures index

Of summaries and scale

The Bibliography and Intertextual Gestures index pages form the core of WWIN. However, the scale of the data represented in them can make those indexes a daunting place for readers to begin exploring. In Figure 4, for example, the WWIN interface reports that there are a total of 25,727 intertextual gestures across 515 pages of results — far too many to skim for some interesting tidbit. The Filter results sidebar helps a great deal, but each category is limited to only the top ten filters. One would have to view the JSON or XML data to see all possible filters at once.^[4] Similarly, sorting allows page one to appear repopulated with a different set of results. But even so, there is not much chance that a person will navigate through every page of results to build a picture of the full dataset.

As previously mentioned, WWIN was intended to enable exploration: to make the scope of intertextuality in WWO visible, to bring patterns into focus, and to showcase the interconnectivity of the data. To this end, the bibliography entry pages and two additional indexes showcase donut chart visualizations which give a high-level overview of intertextual usage across WWO.

Figure 5: Summaries of intertextual gestures by and within the novel Romance Readers and Romance Writers.

Screenshot selected from the Romance Readers and Romance Writers bibliography entry page.

These visualizations — donut slices and the legend entries alike — also serve as links into the Intertextual Gestures index, allowing readers to easily navigate to a table of all relevant gestures. The visualizations summarize and break down the data, yes, but they also reward curiosity. The reader can interrogate the data behind the chart by simply clicking a link.

It is worth emphasizing that the website user has a lot of power to control their experience of WWIN. To enable this level of control, the website must aggregate all relevant data in order to display a single page of results. The WWIN dataset is not a huge dataset, but it is large enough that aggregation has a heavy processing cost.

Another project might have chosen an easier approach; for example, by implementing a single index of source documents. Each record might then show a narrative view of all the intertextual gestures within that source text. This would have reduced the amount of data that we needed to compile. It also would have shifted our development more toward XSLT rather than XQuery.

However, this approach and others would have limited WWIN to document-by-document explorations of intertextuality. The Women Writers Project was more interested in giving users the tools to explore intertextuality across the textbase, working at scale to find patterns of use, and then drilling down into the context of each individual gesture. As a result, the author focused eir pre-publication efforts on building up the indexes of WWIN.^[5]

Enter the EXPath app

Behind the scenes, Women Writers: Intertextual Networks is an EXPath application served out of the WWP’s eXist-db instance.^[6] The EXPath package contains several XQuery scripts and libraries. One library contains functions with RESTXQ annotations, and is used to serve out the WWIN website pages. The compiled EXPath package also includes: a clean, publication-friendly version of the XML bibliography (no comments, internal notes, or proofing flags, for instance); a JSON representation of the bibliography; and a TEI personography derived from keyed contributor names.

Besides the bibliography (stored in the application directory) and WWO documents (stored in a WWO-specific data directory), the EXPath app maintains a separate directory of intertextual data compiled from these two sources. In order to save processing on inferred knowledge, the RESTXQ endpoints draw from this data cache, rather than directly querying the TEI.

The data cache is generated ahead of time through a series of XQuery scripts. The caching process was designed to be modular for debugging and logging purposes.^[7] Each XQuery builds off the inferences made by the last, saving its output to a staging directory. By the end of the process, a final script has moved all caches out of the staging directory and into the publication directory, ready for use. (A thorough description of the XQuery workflow can be found in the Caching Processes appendix.)

The published caches include:

Except for the XHTML serializations, the caches were stored in the W3C’s XML serialization of JSON (nicknamed pseudo-JSON by the author).^[9] With eXist able to index these files as XML, the web app could identify caches that matched a request’s criteria. Cached XML was then parsed as maps or arrays, which could be passed around, augmented, and serialized quickly as JSON or XML, or (with a bit more effort) as HTML. An example of the cached pseudo-JSON can be found in Appendix C.

By spring 2022, the staging site for WWIN was admittedly a little slow, but stress tests with small groups of human users didn’t phase the test server too badly. And so, on May 25th, 2022, with WWIN freshly installed on the WWP production instance of eXist, the Women Writers Project announced the public release of WWIN.

This is not where things went wrong

…because publishing WWIN did not reveal anything new about the quirks and eccentricities of the web app. What publishing did was escalate the behaviors that were already there, transforming quirks into legitimate problems.

When the Women Writers Project announced that WWIN had been published, traffic skyrocketed. This was not just casual users and well-wishers, but also bots. Bots which followed every link to every facet, causing the app to spend a lot of time generating caches of XML for requests it hadn’t anticipated. The processing time could take over a minute, in which case the Apache server would cut the user’s connection and display an error. While that user was refreshing the page, eXist might still be processing the original request, in which case the WWIN app would begin the process again from the start.

Once a response was cached, a subsequent request would get a much speedier response. Still, bots were guaranteed to follow every combinatorial iteration of every index, and WWIN was struggling to keep up with so much traffic.

The WWP production server was struggling too. The server housed our entire main website, as well as WWO and eXist. As eXist consumed more of the server’s memory and computational power, the rest of the WWP universe also began to operate with a noticable sluggishness.

The author’s first task post-launch was to move eXist off the WWP server and into the cloud. E coordinated with Northeastern Library developer and Amazon Web Services whiz Robert Chavez to create an Amazon EC2 instance, which would have only one job: to house eXist and send content to the WWP production server. We gave this new eXist instance a lot of memory and CPUs with which to work. This infrastructural update stabilized the WWIN app, and freed the production server to use its resources judiciously.

However, page load times were still high as bots continued to work through the indexes. The WWP team was becoming superstitious about using eXist at all, fearful that any nonessential request might bring down the database. Work on the WWIN application clearly could not stop at publication.

Analysis: or, processor pain points

Let’s step back for a moment to talk about some tasks which may be time-, memory-, and processor-intensive:

Of the above tasks, WWIN was originally developed with the first four in mind. As part of the caching workflow, implicit data was made explicit, facets were generated, identifiers were sorted, and the cache format itself made serialization much easier.

The indexes’ responses were paginated, which reduced the number of full records that needed to be retrieved and the amount of transformation work required. However, in order to sort or generate facets, the full dataset needed to be accessed even though only a portion would be serialized for display.

                           
<fn:map key="facets">
   <fn:array key="genre">
      <fn:map>
        <fn:string key="id">political-writing</fn:string>
        <fn:number key="count">19</fn:number>
      </fn:map>
      <fn:map>
        <fn:string key="id">speech</fn:string>
        <fn:number key="count">6</fn:number>
      </fn:map>
      <fn:map>
        <fn:string key="id">legal-writing</fn:string>
        <fn:number key="count">3</fn:number>
      </fn:map>
      <!-- ... -->
   </fn:array>
</fn:map>

Next steps

Improving efficiency in the WWIN application is now a lower priority — further development is likely to add functionality to the web interface rather than to the backend. Even so, the author has other ideas for further improving WWIN’s performance:

Takeaways

This paper described the origins and evolution of the Women Writers: Intertextual Networks EXPath application. The application’s scale and choice of interface led to a data ecosystem that must do as much processing ahead of publication as possible. This ecosystem had to be further optimized for indexing and retrieval of cached data.

In general, the more power you give users to control their own experience of the data, the more work you may have to put into caching variations or subsets. If you are contemplating an index-heavy application like WWIN, decide ahead of time where you must put the work. One of those tasks should be on indexing, both in terms of modelling the XML for retrieval, and in defining the index itself. The smaller and more precise the index, the quicker you’ll be able to obtain a result. The quicker the result gets to your users, the more wonderful their experience will be.

Acknowledgements

The author would like to thank Sarah Connell, Syd Bauman, Julia Flanders, and Rob Chavez for their support on this long journey toward a publication e could actually feel proud of. Thanks also to Meg McMahon, the Women Writers Project encoders, the Northeastern University Library and the Digital Scholarship Group. Finally, thanks to the National Endowment for the Humanities for their generosity in funding this ambitious endeavor.

WWIN perserveres today because of the support of all these wonderful people. Thank you.