On the Descriptions of Data: The Usability of Notations

This presentation was given at Balisage 2018 as an “Encore Presentation”. The Balisage program consisted of all new material on a wide variety of topics related to markup. At the time the program was assembled, the Conference Committee believed that every one of the speakers who accepted a spot on the program would be able to come to Balisage and make a presentation. Unfortunately, sometimes things happen, and from time to time, scheduled speakers are unable to give their presentations. Balisage attendees who have previously delivered markup-related presentations are invited then to offer them as fill-ins. This presentation was such an “Encore Presentation”.

Copy-fitting for Fun and Profit

Copy-fitting is the fitting of words into the space available for them or, sometimes, adjusting the space available to fit the words. Copy-fitting is included in “Extensible Stylesheet Language (XSL) Requirements Version 2.0” and is a common feature of making real-world documents. This talk describes an ongoing internal project for automatically finding and fixing problems that can be fixed by copy fitting in XSL-FO.

Documentation of XSLTs with Code Intelligence

We benefit more from documenting why certain functionality was implemented, or coded in a particular way in an XSLT stylesheet, than from the typical “what the code does” comment. K7:XSLTDocEngine is a personal project (non-commercial) to create XSLT stylesheet documentation from both inline stylesheet comments and documentation living outside the stylesheet. The external documentation lives in XML files, written in a variant of DocBook, that are generated by script and populated by XSLT analysts. These files are then used to generate configurable HTML documentation that provides the text as well as 1) hyperlinks to named templates, global variables and functions, imported/included templates and 2) reports of code violations such as potentially overridden functions, single-expressions, unused variables, and the like. Code violation criteria are defined in user-configurable rule sets.

An Adventure with Client-Side XSLT to an Architecture for Building Bridges with Javascript

This paper describes the development process we undertook to extend the capabilities of an XML-based authoring and publishing system. Originally designed to deliver content for print and the web, we transformed it into one that delivers fully interactive web-based wizards whose steps are generated automatically based on logic encoded into the source documents. To meet our requirements for the application, we rejected conventional top-down XML or JavaScript frameworks and instead sought to unite JavaScript and XSLT to leverage the strengths of each. Despite being underutilized as a client-side technology, XSLT is still a valuable tool in the development of modern web applications. Its expressive nature, continuing support in browsers, and ability to integrate with a modern virtual DOM-based user interface framework allowed us to build a complex legal forms application that was simpler and more productive than more conventional approaches. Our application demonstrates opportunities for symbiosis with client-side XSLT that has potential beyond legal forms and for an architecture with implications beyond XSLT.

Fractal information is

We wrestle often with the granularity of data formats, object models, interfaces, and APIs: their strengths, their weaknesses, and the supports they provide to creators and consumers. Opinion is often muddled or extrapolated from limited experience: “X is lightweight”, “Y is ‘self-describing’”, “everyone prefers Z”. This is a fractal experience; there is self-similarity across scales. Issues that arise at one level of the system have weird echoes elsewhere. Indeed, one way of discriminating among options (XML, HTML, Markdown, JSON, YAML, SAX, DOM, etc.) is to consider their different approaches to the problem of managing the chaos and representing (ir)regularity. This examination leads to a better understanding of how to exploit their differences to make them work better together.

In Defence of Style Guides

This is a paper about that twilight zone beyond schemas, the place where style guides, those arcane instructions to authors about house style and how to produce content that is not only valid but stylistically consistent, are supposed to kick in but, these days, increasingly don't. It's a paper written in defence of style guides, why they are needed, and why better tools cannot replace them.

Using Excel Spreadsheets to Communicate XML Analysis

What is the best approach for analyzing large XML datasets? Reading thousands (or possibly millions) of pages of raw XML to fully understand the markup constructs? This approach is just not feasible. CSS stylesheets are useful for displaying a few files of XML data but is not really efficient. I have found creating analysis information in Excel spreadsheets is a very useful tool for understanding the full XML data constructs. This approach is also understandable to stakeholders when trying to convey useful information about their datasets. This paper will describe an approach for creating document analysis Excel spreadsheets using XSLT and XML.

Easing the road to declarative programming in XSLT for imperative programmers

As most programmers learn their trait in mainstream languages like C, C#, Java or nowadays in Python, PHP, Objective-C or Ruby, it is sometimes challenging to switch the mindset from such imperative languages to the declarative nature of XSLT. In this talk I will represent a way to map your imperative mindset to the declarative and functional one of XSLT and XPath. We will be revisiting the structure of an XSLT stylesheet and how you can understand its flow from an imperative standpoint, or how to make changes to existing stylesheets without resorting to frustratingly deeply nested xsl:if and and xsl:choose elements. You may already have come to understand that you should not think in opening and closing tags, but instead in trees and traversals, but if you haven't then this may help you get there. In imperative languages you tell the computer what to do, step by step. In declarative and functional languages, you tell the computer what result you wish for, and how it depends on your input. You guide the processor with a soft hand and give it suggestions, instead of imperatively making finite decisions for the compiler one by one. There's no need to become a fully fledged functional programmer and understand all its paradigms before you can be relatively versatile with writing effective XSLT stylesheets. I hope this talk will provide insights that help both the seasoned XSLT programmer and the beginning or interested imperative programmers to improve their skills and, most importantly, to not be afraid of the wolf.

Stand-off Bridges in the Frankenstein Variorum Project

Developing the Frankenstein Variorum Project has necessitated a reconciliation of extremely divergent markup ecosystems supporting multiple editions of a single novel. The reconciliation process involves breaking or flattening the original hierarchies to prioritize units of low-level lateral intersection, points shared in common to construct “bridge” or intermediary formats for processing with automated collation via CollateX. The output from the automated collation process also serves as an intermediary format that we transform into a TEI form of stand-off parallel segmentation, in which stand-off pointing mechanisms operate like a switchboard for connecting the individual editions which can remain (for the most part) undisturbed or unmarked from the collation process. The TEI “stand-off bridge” negotiates the distinct markup ecosystems in ways that can break the “silo” effect of isolating specially encoded editions. Far from an ephemeral support structure, the stand-off bridge upholds the whole as the “spine” of the variorum project because it improves the interoperability and interchangeability of all the markup ecosystems involved. Building the stand-off bridge effectively reconstitutes the hierarchies in a way that expresses intersections essentially as a graph structure of nodes with edge pointers to comparable nodes. Our experience on the Frankenstein Variorum is consistent with other TEI projects that involve the curation of divergence, variance, and forking in text streams. Taken together, such projects illuminate how the TEI can organize textual data in ways other than an ordered hierarchy of content objects, and that the TEI can be turned to express unordered “lateral” intersections in ways that serve long-standing goals of the TEI community: interchangeability and interoperability of electronic texts. As Syd Bauman in particular has discussed, where interchangeability reflects the capacity for humans to negotiate and adapt to markup ecosystems from systematic navigation and documentation without needing to contact the encoder for help, interoperability reflects the capacity of software tools to process the markup without needing to change either it or the tools. Although we usually consider the needs of software interoperability as at odds with the richly expressive capacity of human-readable semantic interchange, this paper suggests that the TEI can be designed to prioritize the interests of both, from facilitating automated collation to generating an interlinking web interface that gives the user means to choose and change directions in navigating multiple editions as desired.

YAMC? Why are we here? Why are we here again?

There is nothing new about markup, or even generic markup. (I have been working with generic markup for 40 years!) So what is there to talk about after all this time? What are we accomplishing by gathering at Balisage: The Markup Conference? Why do some of us find events like this one valuable? What can you do to make it valuable to you and to the others here? Not only is markup old hat, XML is 20 years old, and some people in the outside world keep trying to tell us that its time has passed. Groups are still gathering to create shared markup vocabularies in order to enable high quality information sharing. Scholars are using bespoke markup vocabularies to enable them to focus on the works they are reading, interpreting, and writing. Trendy end user displays are being populated by solid maintainable XML content. An ever-improving tool set is available to users of marked-up documents. We learn from each others’ projects, tools, techniques, and experiences — and enjoy the process!