Balisage Paper: It’s Complicated: Holistic Approaches for Considering Complexity in XML Documents

Note to the reader

A link to an updated version (or even a newer edition) of this paper may be available on the WWP bibliography page.

Introduction & argument

This paper explores the impacts of complexity on the creation and use of XML documents, with a focus on human experiences of complexity. In order to discuss this topic in detail, it would be helpful to have a method of measuring complexity, which we assert does not (yet?) exist. Furthermore, complexity in the markup itself does not always correlate with complexity in writing, proofing, reading, and processing the XML — what one might call operational complexity. Thus, measurements of complexity that focus purely on metrics — counting elements or attributes, comparing the density of markup relative to textual contents, measuring the diversity of element types — provide only a partial view of complexity from the perspective of the projects and individuals using the XML. For example, the Text Encoding Initiative provides an <lb> element for marking the beginning of new lines. Using <lb>s to encode each new line from a printed source text might expand the number of elements in a document by the tens of thousands, but this also makes the document dramatically easier to proofread, navigate, and compare with the source file. In this paper, we discuss some features of complexity as it impacts the sharing and reuse of XML files, the longevity and sustainability of XML projects, the consistency and quality of encoded texts, and the planning and implementation of encoding work.

While the authors must confess an interest in measuring complexity for its own sake, increased precision around understanding and weighing the sources of complexity faced by XML projects is also essential for anticipating and mitigating these. As we discuss below, it is often the case that projects can choose to relocate complexity from one process or stage of project development to another — for example, making the encoding more complex in order to simplify processing, or the reverse. Approaching such decisions strategically requires that projects are able to: 1) recognize the full spectrum of locations in which complexity will manifest, 2) measure (or, at least, evaluate) those sources to determine where relocating complexity will most impact the project’s efficiency, 3) recognize both where complexity is unavoidable and where any processes or decisions will lead to unnecessary complexity, and 4) iteratively revisit the project’s processes to determine where these may need to be adjusted. By offering a framework for identifying sources of complexity in XML project work and suggesting additions to syntax-based complexity metrics, we hope to offer some considerations that will be useful to XML project planning and discussions around understanding complexity in work with XML.

As C. M. Sperberg-McQueen argues in his closing keynote from Balisage 2021, complexity is an issue that most XML projects need to address. He writes:

This paper is far from the first to consider the ways that complexity in XML documents and schemas can be measured. Numerous studies, especially in the computer sciences, have offered metrics for evaluating XML complexity. For instance, Ruellan (2012) offers a comprehensive formal study of the quantity of information contained in XML documents, classifying XML complexity according to three metrics:

In this paper, we will refer to such metrics as syntactic complexity. In no way do we wish to suggest that syntax is not useful for understanding the impacts of complexity on work with XML; indeed, we offer several of our own approaches for considering a variety of syntactic features. However, we wish to expand upon syntactic metrics to explore several other sites of complexity in XML workflows, including the semantics of the markup, the ways that markup is edited and processed, and the lifecycles of XML files. As might be clear already, this paper is situated within our own perspective of working with XML files primarily in the context of digital humanities projects. We think that this perspective is generalizable enough to be relevant in many — although, of course, not all — other applications. We offer this framework as a resource for continued work on studying the impacts of complexity on the use and sustainability of XML files.

We locate several sources of complexity within XML files and related systems. These include measures that evaluate XML files directly:

Schemas are another essential site for understanding XML complexity, as examined in several previous studies.^[2] In considering schema complexity, we touch upon complexity within schemas themselves; we also look at several ways that schemas impact operational complexity. And finally, we locate complexity within the minds of the humans writing and interacting with XML files. Relevant to the human element of complexity in XML is what we call visual complexity, as experienced due to the appearance and layout of the markup. This is a space where humans and computers can diverge dramatically, since features such as indentation and whitespace can strongly impact complexity as perceived by humans.

Having outlined our approaches to understanding and beginning to measure complexity, we offer two brief case studies that reveal further complications that emerge through the intersection of human activities and XML syntax. Here, we think about ways that XML files can become complicated in terms of being difficult to work with, with attention to cases in which the things that make XML files challenging do not correlate with the obvious forms of syntactic complexity. First, we consider the usage of renditional defaults (a method for declaring the default value of an attribute) in TEI files. From some perspectives, renditional defaults make TEI files dramatically simpler, since they can reduce the number of attributes specifying rendition for individual elements by the tens of thousands. However, renditional defaults have a dramatic impact on operational complexity, since they mean that encoders must remember to override them where necessary, proofreaders need to keep them in mind when reading encoded files, and systems for processing the encoded files must take into account the fact that rendition might be specified either locally or through defaults. In the second case study, we consider the use of sequence vs. containment as information storage methods with respect to complexity, positing that neither is particularly complicated on its own, but that mixing the two may increase complexity without any obvious benefit.

As the above indicates, this paper is deeply invested in seeking to understand where complexity is located within XML systems. This goal requires that we also address how complexity is defined. As with its measurement, the definition of complexity has received considerable scholarly attention; a thoughtful and comprehensive overview of this work can be found in a recent article by Beale et al. (2024)^[3] This article characterizes the definition of complexity as contentious, outlining sources and usages of several definitions before offering the following definition, based on the authors’ analysis of usage insights: complex(ity) is when relationships between elements are weaved together such that they are not fully comprehended, leading to insufficient certainty between cause and effect (Beale et al. (2024)). The relationship between complicated and complex is also an important definitional touchpoint: as Beale et al. explain, the majority of dictionaries treat these terms as synonyms, reflecting their most widespread usages, while complexity theory treats the two terms as fundamentally distinct. The precise difference between complex and complicated is yet another space where there is considerable divergence of thought — generally, systems or processes can be described as complicated whenever they possess many components, while there is a higher threshold for ascribing complexity, usually involving unpredictability or a whole that cannot be comprehended by examining its parts. A useful framework for distinguishing these terms is published in the Complex Systems Frameworks Collection by Diane Finegold (Finegold (2022)). Here, complicated systems are described as predictable, controllable, and designable (that is, possible to design around). Complex systems, by contrast, are inherently unpredictable, heterogeneous, non-linear, and with interdependent parts that impact each other’s behavior.

These distinctions can be useful in recognizing which strategies will work best to manage any aspects of a project, whether complex or complicated, that are not conveniently simple. That said, in the authors’ experiences, complexity and complication exist on a spectrum — for the individuals working on a project, anything that becomes complicated enough will also be complex to work with. Our primary goal for this paper is to locate and assess the complexities that are experienced in XML project work so that these can be better anticipated and managed. Thus, for us, the most important meaning of complexity would be the one used and experienced by the individuals designing and implementing XML projects. In the discussions that follow, we treat complex systems as ones involving multiple component parts that interact in ways that are difficult to predict. Since we recognize that so much of the direct experience of complexity is perspectival — given that one project’s complicated will be another project’s complex — we use the term complex when it seems likely that the phenomenon under discussion might be either complex or complicated, depending on the circumstances. We reserve the term complicated for situations in which it seems clear that the features under discussion are only complicated.

If we may be forgiven the potential tautology, this paper argues that complexity is complicated — complexity itself comprises many individual components. Here, we wish to expand our understanding of XML complexity by thinking seriously about how these various components interact. Despite our interest in measurement, we are keenly aware that there is no single yardstick that can be used to quantify complexity — as Sperberg-McQueen notes, complexity is sometimes in the eye of the beholder (Sperberg-McQueen (2021)). The weight and impacts of complexity will depend on the XML, the person reading the XML, the data, the needs of the project, and so on. Nevertheless, we think that having more precise vocabularies for describing complexity — in addition to more detailed understandings of how these different forms of complexity interact with human work — can only help. This paper is an effort to begin developing such vocabularies and understandings.

Locations of complexity

In the XML instance

We find complexity (and simplicity, but that’s not important right now) in various places in our lives in general, and in our XML in particular. The first complexity that most of us think of is the syntactic complexity of the XML instance itself. This notion is supported by the fact that all of the prior work we discovered in a literature review of XML complexity metrics was about the complexity of XML instances.

Syntactic

But we submit that, even when only talking about syntactic complexity — which should be the easiest to define — that we (at least we, the authors, if not we, the entire XML community) do not know what makes an XML instance more or less complex. Nonetheless, there is no doubt that some documents are simple — see Figure 1.

Figure 1

<?xml version="1.0" encoding="UTF-8"?>
<msg>Hello World!</msg>

And there is very little, if any, doubt that some are complex — see Figure 2.

Figure 2

A screenshot of ~6,120 characters worth of a single line of XML (being edited in Emacs/nxml-mode on Ubuntu). It contains 86 start-tags, 91 end-tags, and 50 attributes.^[4]

What is not clear is whether or not there is any agreement as to which ones are complex, or what contributes to complexity. But I know it when I see it à la US Supreme Court Justice Potter Stewart is not helpful with respect to automated complexity detection, and is, to our knowledge, completely untested. That is, no one has heretofore determined that human perception of complexity matches any particular metric of syntactic complexity, or even measured inter-reviewer reliability of complexity detection in XML.

Raw counts

Which begs the question: where might we look for metrics of syntactic complexity? Simple raw counts of syntactic structures may well be helpful, and are easy to produce. These raw counts could include (but are not remotely limited to) things like the following.

• The ratio of element instances to the number of characters in the file

• The ratio of element instances to the number of characters in text nodes

• The ratio of element instances to the number of characters in text nodes other than whitespace-only text nodes

• The ratio of element types to element instances (which, when subtracted from 1, is what Ruellan calls structure regularity)

• The ratio of attributes to element instances

• The average length of attribute values

• The average and maximum nesting depth of elements (the minimum is not interesting, it is ‘1’ :-)

Note that we are often using ratios and averages of simple raw counts, rather than the counts themselves, in an attempt to reflect our intuition that filesize itself does not contribute to complexity.

It is our instinct (with little to no evidence) that no single simple raw count, average, or ratio will effectively represent what humans perceive as syntactic complexity, but that some combination of a few of these may.

Fuzzy counts

By fuzzy counts we do not mean counts that are not precise, but rather precise counts of less rigid phenomena. One big problem with the simple raw counts of precise syntactical structures is that it does not take into account even the syntactic complexity, let alone the semantic complexity, of some element types vs others. For starters, those syntactic structures that are used to handle overlap problems (e.g., the TEI’s @next & @prev attributes) lend significant complexity to an instance, in that the data needs to be represented as or at least considered as more than a single simple tree structure.

Consider the TEI <g> element; its name is short for gaiji or 外字, meaning (for our purposes) a character that is not available in Unicode. It is in many ways parallel to the <c> (for character) element, but rather than contain as content a Unicode character, it points via an attribute to an XML structure that describes a character. This adds some semantic complexity, sure; but just syntactically speaking, does a <g> element count as zero characters of content (because it is empty), one character (because it represents one character), or however many characters are used to describe the one character?

If you are counting words in a document, how do you account for an acrostic? I.e., does Figure 4 have five words or six?

Figure 4

    <surface>
      <line>Tyrannical</line>
      <line>Racist</line>
      <line>Unqualified</line>
      <line>Misogynistic</line>
      <line>Panderer</line>
    </surface>

And while Figure 5 has 10 <w> elements, the encoder is asserting it has six words.

Figure 5

    <surface>
      <line><w><w xml:id="ac.01"               next="#ac.02">T</w>yrannical</w></line>
      <line><w><w xml:id="ac.02"prev="#ac.01"  next="#ac.03">R</w>acist</w></line>
      <line><w><w xml:id="ac.03"prev="#ac.02"  next="#ac.04">U</w>nqualified</w></line>
      <line><w><w xml:id="ac.04"prev="#ac.03"  next="#ac.05">M</w>isogynistic</w></line>
      <line><w><w xml:id="ac.05"prev="#ac.04"               >P</w>anderer</w></line>
    </surface>

Syntax ↛ Semantics

It is worth noting that syntactic complexity does not necessarily imply semantic complexity. It is not unusual when using a major tagset like JATS, DocBook, or TEI to find cases for which it takes quite a bit of XML syntax to represent relatively straightforward concepts. E.g., when encoding the libretto for The Phantom of the Opera in TEI, if one wishes to indicate that the first letter sent by the Phantom is, in fact, a letter, one may end up with the encoding in Figure 6.

Figure 6

  <sp who="#and">
    <speaker>ANDRE</speaker>
    <quote>
      <floatingText type="letter">
        <body>
          <salute>Dear Andre</salute>
          <l>what a charming gala!</l>
          <l>Christine enjoyed a great success!</l>
          <l>We were hardly bereft</l>
          <l>when Carlotta left</l>
          <l>otherwise</l>
          <l>the chorus was entrancing,</l>
          <l>but the dancing was a</l>
          <l>lamentable mess!</l>
        </body>
      </floatingText>
    </quote>
  </sp>

No doubt many will find it at least annoying, if not problematic, that the assertion he (the character) is reading a letter requires encoding an extra three levels deep.

As another example, the extract shown in Figure 7 is from a sample article published on the NLM website.

Figure 7

  <p>We report on … 14 relevant papers.
    <boxed-text>
      <sec>
        <title>Summary points</title>
        <p>
          <list list-type="bullet">
            <list-item>
              <p>Longer consultations are … better patient outcomes</p>
            </list-item>
            <!-- ... -->
            <list-item>
              <p>Research on implementation is needed</p>
            </list-item>
          </list>
        </p>
      </sec>
    </boxed-text>
  </p>

Here text is encoded six levels deep to indicate a list item that is in a separate box.

Semantic complexity

Syntax is not the only site of complexity within XML documents — semantic complexity also has a significant impact on writing and working with XML. These two forms of complexity often operate independently; as we saw above, relatively simple concepts may require quite deep nesting. The reverse is also true — the meaning expressed through markup might itself be complex or deeply theoretical even if the encoding at stake is straightforward. For instance, the Women Writers Project, a longstanding TEI project focused on early women’s writing, uses a custom <hyperDiv> element to contain features that the WWP has identified as hypertextual.^[5] These include annotations, names spelled out in acrostic poems, invented cast lists (for characters who speak within a drama but are not included in the play’s printed cast list), and other phenomena that operate hypertextually. <hyperDiv> is a single element with a restricted set of permitted contents,^[6] but it represents the WWP’s very particular theory of how texts function as developed over decades of encoding pre-Victorian women’s writing. <hyperDiv> may not add much to the syntactic complexity of a document, but the semantic complexity expressed through this theory of how texts function is substantial.

Semantic complexity impacts XML project work because of the time needed both to develop and to apply semantically rich encoding practices. For example, the WWP collaborates with editors Noelle A. Baker and Sandra Petrulionis on encoding the Almanacks of Mary Moody Emerson for publication within the Women Writers Online collection. Among the features represented in the XML are Emerson’s famously capacious inclusions of other authors’ language within her commonplace Almanacks. Most of these are encoded with a custom <itg> (intertextual gesture) element, with greater specificity provided through the @type attribute. In cases where Emerson hews more closely to her source language, <quote> and @type are used instead. @source is also used to indicate the source of the referenced text.^[7]

The encoding at stake is relatively simple; each instance requires only one element and two attributes. A sample of this encoding is found in Figure 8.

Figure 8

<itg type="dialogic_reference" source="mb:Fellowes_Picture">These
<choice><abbr>tho’ts</abbr><expan>thoughts</expan></choice> have passed my 
<lb/>own mind in much the same connection.</itg>

Sample from the Women Writers Project XML encoding for Emerson Almanacks showing the project’s use of <itg>.

However, the nuance and the critical interpretation of Emerson’s commonplacing practices being expressed through this encoding is much more significant. Some values used by the project include:^[8]

allusion	An implied or indirect, but deliberate, reference to another text
dialogic reference	Dialogue or direct address to authors or source material, or commentary on both in the form of debate, argument, or pondering/musing; or placement of authors in dialogue with each other
distillation	A synthesis of materials from a text or set of texts; may include direct quotation
paraphrase	A summary or representation of the meaning and content of material from another text that may or may not include some direct quotation of the original language
reference	A mention, typically brief, of material from another text
repurposing	A representation of material from another text that deliberately changes the meaning of the original

As the list above suggests, this encoding draws quite fine distinctions among the different ways that Emerson weaves the ideas and writing of others into her Almanacks. Application of this encoding is only possible after considerable research on the parts of the editors, with careful comparison between Emerson’s Almanacks and the language in her (many) sources. With two elements and a @type attribute, this markup expresses a semantically rich reading of Emerson’s multivalent commonplacing practices. The simplicity of the syntax for this encoding belies the rich editorial expertise that was necessary to develop and apply this list of values.

Of course, it is also possible for syntactic and semantic complexity to appear in tandem — our point here is that one is not a predictor for the other. Perhaps the simplest way to demonstrate this insight is to consider the possibility that the same meaning might be expressed with completely different markup. For instance, it is generally agreed that the two encodings in Figure 9 are semantically precisely the same.

Figure 9

<msg level="error"
     code="XTTE0570"
     text="An empty sequence is not allowed as the value of variable $fn"/>

  <msg>
    <level>error</error>
    <code>XTTE0570</code>
    <text>An empty sequence is not allowed as the value of variable $fn</text>
  </msg>

Any measure of syntactic complexity that focuses on counting elements will find that the second example is more complex, since it uses four elements instead of one to express the same meaning. Along the same lines, the TEI element <placeName> means the same thing as the <name> element with a value of place on @type. The things that make <placeName> harder or easier for an encoder to understand are separate from the things that impact how long it will take an encoder to type <placeName> or to type <name> and add a @type attribute and value. The syntactic complexity changes, depending on which option is used, but the semantic complexity stays the same.

For the kinds of complexity we are interested in — those that impact human work on XML projects — it is helpful to keep both semantic and syntactic complexity firmly in view. Moreover, we can broaden our view even further and consider the systems that surround XML documents. The next section discusses complexity within the processing, application, and versioning of XML files.

zero_or_more_in_alternation = ( a | b | c | d | e | f | g | h | i | j )*
start = element confusing { zero_or_more_in_alternation }
a = element a { zero_or_more_in_alternation }
b = element b { zero_or_more_in_alternation }
c = element c { zero_or_more_in_alternation }
d = element d { zero_or_more_in_alternation }
e = element e { zero_or_more_in_alternation }
f = element f { zero_or_more_in_alternation }
g = element g { zero_or_more_in_alternation }
h = element h { zero_or_more_in_alternation }
i = element i { zero_or_more_in_alternation }
j = element j { zero_or_more_in_alternation }

<?xml version="1.0" encoding="UTF-8"?>
<confusing>
  <a>
    <b>
      <c>
        <d>
          <e>
            <f>
              <g>
                <h>
                  <i>
                    <j/>
                  </i>
                </h>
              </g>
            </f>
          </e>
        </d>
      </c>
    </b>
  </a>
  <a>
    <b/>
  </a>
  <c>
    <d/>
    <a/>
  </c>
  <e>
    <c/>
    <f/>
    <i/>
  </e>
  <g>
    <a/>
    <h/>
    <b>
      <h/>
    </b>
  </g>
  <i>
    <j/>
  </i>
  <b>
    <c>
      <d>
        <a>
          <f/>
          <g/>
          <e/>
          <i/>
          <h/>
        </a>
        <j/>
        <b/>
      </d>
    </c>
    <e>
      <f>
        <h>
          <g>
            <e/>
          </g>
        </h>
      </f>
      <a/>
      <b>
        <j>
          <h/>
        </j>
        <e/>
      </b>
    </e>
  </b>
</confusing>

<?xml version="1.0" encoding="UTF-8"?>
<lg type="limerick" rhyme="aabba" n="3">
  <head>Warp Speed, Ms Bright!</head>
  <l>There was a young lady named Bright,</l>
  <l>Who traveled much faster than light,</l>
  <l>She departed one day,</l>
  <l>In a <term xml:id="t17">relative</term> way,</l>
  <l>And returned on the previous night.</l>
  <note target="#t17">See
    <ptr target="http://en.wikipedia.org/wiki/Theory_of_relativity"/>.</note>
</lg>

start = lg
lg = element lg {
  attr.type?,
  attr.rhyme?,
  attr.n?,
  head?,
  l, l, l, l, l,
  note*
  }
attr.type = attribute type { token }
attr.rhyme = attribute rhyme { token }
attr.n = attribute n { xsd:nonNegativeInteger }
head = element head { stuff }
l = element l { stuff }
term = element term { text }
ptr = element ptr { target, empty }
note = element note {
  target,
  stuff
  }
target = attribute target { xsd:anyURI }
stuff = ( text | term | note | ptr )*

start = lg
lg =     element lg    { attrs, ( text | lg | head | l | term | note | ptr )* }
head =   element head  { attrs, ( text | lg | head | l | term | note | ptr )* }
l =      element l     { attrs, ( text | lg | head | l | term | note | ptr )* }
rhyme =  element rhyme { attrs, ( text | lg | head | l | term | note | ptr )* }
term =   element term  { attrs, ( text | lg | head | l | term | note | ptr )* }
note =   element note  { attrs, ( text | lg | head | l | term | note | ptr )* }
ptr =    element ptr   { attrs, ( text | lg | head | l | term | note | ptr )* }
attrs = ( attr.type, attr.rhyme, attr.n, attr.target )
attr.target = attribute target { text }?
attr.type =   attribute type   { text }?
attr.rhyme =  attribute rhyme  { text }?
attr.n =      attribute n      { text }?

start =
  element lg {
    attribute type { "limerick" },
    attribute rhyme { "aabba" },
    attribute n { "3" },
    element head { "Warp Speed, Ms Bright!" },
    element l { "There was a young lady named Bright," },
    element l { "Who traveled much faster than light," },
    element l { "She departed one day," },
    element l {
      mixed {
        element term {
          attribute xml:id { "t17" },
          "relative"
        }
      }
    },
    element l { "And returned on the previous night." },
    element note {
      attribute target { "#t17" },
      mixed {
        element ptr {
          attribute target {
            "http://en.wikipedia.org/wiki/Theory_of_relativity"
          }
        }
      }
    }
  }

<p>The first wife of <persName>Captain Olney</persName>, and mother of
  <lb/>his children, died on
  <date when="1813-12-13">13th of <name>December</name> 1813</date>.
  …
  On <date when="1830-03-25"><name>March</name> 25th,
  <lb/>1830</date>, he addressed the following letter to … </p>

  <xsl:sequence>
    <xp:if>
      <xp:test>
        <xp:varRef name="title"/>
        <xp:binop name="equals"/>
        <xp:string/>
      </xp:test>
      <xp:then>
        <xp:function name="string-join">
          <xp:arg n="1">
            <xp:function name="distinct-values">
              <xp:arg n="1">
                <xp:path>
                  <xp:step axis="child">
                    <xp:ref type="element" ns="http://www.w3.org/1999/02/22-rdf-syntax-ns#" name="Description"/>
                  </xp:step>
                  <xp:step axis="child">
                    <xp:ref type="element" ns="http://ns.exiftool.org/File/System/1.0/" name="Directory"/>
                  </xp:step>
                </xp:path>
              </xp:arg>
            </xp:function>
          </xp:arg>
          <xp:arg n="2">
            <xp:string>, </xp:string>
          </xp:arg>
        </xp:function>
      </xp:then>
      <xp:else>
        <xp:function name="translate">
          <xp:arg n="1">
            <xp:varRef name="title"/>
          </xp:arg>
          <xp:arg n="2">
            <xp:string>_</xp:string>
          </xp:arg>
          <xp:arg n="2">
            <xp:string> </xp:string>
          </xp:arg>
        </xp:function>
      </xp:else>
    </xp:if>
  </xsl:sequence>

  <l>Whil'<choice><sic>f</sic><corr>ſ</corr></choice>t the fair Nymphs Eyes apace</l>

  <l><choice><sic>Whil'ft</sic><corr>Whil'ſt</corr></choice> the fair Nymphs Eyes apace</l>

<placeName>Haverhill</placeName>

Complications of complexity

Now that we have established an inventory of the many sites at which complexity impacts XML projects, let us situate some actual encoding practices within this framework. Here, we will focus on instances where the obvious forms of syntactic complexity are not what makes markup difficult to work with.^[13] We will examine the forms of complexity that increase human time needed for:

Our analysis is situated within the perspective of digital humanities project work — and TEI encoding in particular — and we are far from being able to offer any Grand Unified Theory of XML Complexity. But we do hope our work can help move XML studies toward a more complete understanding of complexity so that projects will be better able to predict and manage its impacts on their work.

<epigraph rend="post(#rule)align(left)indent(1)">
  <quote rend="pre(“)post(”)" source="b:IT02328.4" xml:id="q001">
    <lg type="indeterminate">
      <l>—All beneath th' unrivall'd rose,</l>
      <l>The lowly daisy sweetly blows;</l>
      <l>Tho' large the forest monarch throws</l>
      <l rend="indent(2)">His army shade,</l>
      <l>Yet green the juicy hawthorn grows,</l>
      <l rend="indent(2)">Adown the glade.</l>
    </lg>
  </quote>
  <bibl rend="align(right)case(smallcaps)" source="b:IT02328.4" xml:id="b001">
    <author><persName ref="p:rburns.fgh">Burns</persName></author>.
  </bibl>
</epigraph>

  <tagsDecl>
    <rendition selector="p">first-indent(1)</rendition>
    <rendition selector="quote, said">pre(“)post(”)</rendition>
    <rendition selector="head">align(center)</rendition>    
  </tagsDecl>

  <respStmt>
    <persName>Ronen Barzel</persName>
    <resp>animation software engineer</resp>
  </respStmt>

      <publicationStmt>
        <publisher>Balisage</publisher>
        <idno type="fn">Bal2026con0503</idno>
        <idno type="DOI">10.4242/BalisageVol31.Connell01</idno>
        <date when="2026-10-01"/>
        <distributor>Northeastern University Women Writers Project</distributor>
        <address>
          <addrLine>SL 371</addrLine>
          <addrLine>Northeastern University</addrLine>
          <addrLine>360 Huntington Avenue</addrLine>
          <addrLine>Boston, MA  02115-5005</addrLine>
          <addrLine>USA</addrLine>
          <addrLine>url:mailto:wwp@northeastern.edu</addrLine>
        </address>
        <date when="2026-12-11"/>
      </publicationStmt>

Comparing human assessment of complexity with syntactic metrics

While we have argued here that syntactic measures cannot provide a full picture of the impacts that complexity will have on a project’s use of XML, we are also interested in the ways that syntax interacts with other forms of complexity, especially complexity as experienced or perceived by humans. The 2026 Balisage conference itself was an excellent opportunity to learn more about how humans perceive complexity, and our presentation thus included an experiment during which we asked the audience to weigh in on the complexity of several source documents. We shared five sample documents and asked participants to rank these by complexity, based solely on a visual review of the texts — that is, without using XPath or other methods for direct measurement. Since we expected that participants would find more familiar markup languages less complex (even if asked to set aside personal familiarity for the moment), we selected from a range of languages: JATS, DITA, DocBook, Akoma Ntoso, and TEI. The survey asked participants to rank the five samples from least to most complex, and generated scores for each sample: from 1 for the least to 5 for the most complex. Averaged summary scores assigned by session participants are presented in Table II.

We also asked participants to comment on how familiar they were with each language, selecting from the following options:

Figure 25

A column chart that shows, for each of the five sample XML languages, the number of each familiarity level indicated by the 30 respondents who answered this question.

The scare quotes around the word experiment above should not be taken lightly — this was by no means a rigid, well-controlled, scientific experiment. Among the glaring shortcomings are that our five sample files were a convenience sample; we had only 31 responses, all collected by the end of our conference session; and asking participants to rank the samples, rather than assign each a complexity score, flattened some nuances in service of supporting comparison with the syntactic metrics we calculated for our samples.

Regarding those metrics, we developed a set of 31 candidate measures of syntactic complexity; calculations like average number of element instances per element type and number of element instances plus attributes per KiB of filesize. Prior to the conference presentation we had generated a table that included the scores for each of the 31 candidate measurements for each of the five files (using this stylesheet). After collecting the ranking of sample files from the audience, we compared it to each of the 31 rankings obtained by our candidate measurements (which are summarized in Table IV), and found that none of the rankings from our candidate measurements matched that of the humans in the audience.^[19]

Interestingly, the two samples with the highest scores on the syntactic complexity metrics were at opposite ends of the participants’ rankings: the DocBook sample was ranked as least complex and the Akoma Ntoso one as most complex. It seems clear that language familiarity is playing a role here, as DocBook was also ranked the most familiar language. That said, we also found that there are some notable differences between the complexity scores that participants assigned and their reported familiarity with each language. For instance, TEI was marked the second most complex example, but it was also the second most familiar language. Familiarity scores for TEI, JATS, and DITA were very close, but the DITA sample was marked by participants as much less complex than the other two. Conversely, TEI and DITA have near identical complexity scores by the syntactic metrics (128.18 and 128.88, respectively), while JATS scores somewhat lower (112.48). Correlations seem to fall at the ends of the spectrum: Akoma Ntoso is markedly the least familiar language (according to the responses we received) and was also identified as the most complex sample. Similarly, DocBook was the most familiar language and identified as the least complex sample.

These results become even more striking when one examines the distribution of responses for each language — 50% of respondents reported that they had never seen Akoma Ntoso before, while no respondents said the same of DocBook. On the other hand, 76.6% of participants reported that they had used DocBook at least a few times, if not regularly; only 10% reported the same for Akoma Ntoso. We don’t want to read over-broadly into these results, given the limitations discussed above, but we might be seeing some evidence that the degree of familiarity a person has with a language — in the sense of whether they are an occasional or regular user — has less of an impact than whether the language is totally unfamiliar — in the sense that an XML language will seem more complex when a person is seeing it for the first time.

Concluding thoughts

While there clearly must be a line between simplicity and complexity, it is also clear that to a large extent what will be considered complex (particularly as opposed to complicated) differs from person to person. We have demonstrated here, though, that complexity comprises all sorts of issues in addition to straight-forward syntactic complexity, including the complications involved in applying semantics to markup (both at the stage of initial capture and on reading or processing the marked-up document), constraining markup, processing documents, and reading (by humans of) encoded files.

We have argued herein that syntactic measures cannot provide a full picture of the impacts that complexity will have on a project’s use of XML. We have also demonstrated that the relationship between raw syntactic complexity and complexity as perceived by humans is at best non-trivial to establish. Despite the challenges posed by this problem space, we hope that the frameworks outlined in this paper might make it possible for future researchers to continue addressing the thorny question of how both humans and computers interact with XML complexity — and, even more so, we hope that we have shown how important it is for XML projects to understand the manifold causes of complexity.