Designing Tools for Scientific Thought

This document records what I have learned about the design of “tools for scientific thought” over the past couple years, with an emphasis on the mathematical sciences. One of my goals in writing this is to set out both the unique requirements of an information data model that is needed to record and facilitate scientific thought, as well as the technical requirements for tools that can be used for mathematics.

2022 12 26 https://www.forester-notes.org/tfmt-0002/ tfmt-0002 /tfmt-0002/ Tool for scientific thought Definition

A “tool for scientific thought” could be many things, but it must be a tool for the development and interlinking of scientific ideas in a way that facilitates authoring, publishing, teaching, learning, and the maintenance of .

A tool for scientific thought could be a piece of software, or it could be an organizing principle for physical notes on paper. In these notes, we will primarily explore the design of computerized tools for scientific thought.

2022 12 26 https://www.forester-notes.org/tfmt-0004/ tfmt-0004 /tfmt-0004/ Existing tools for scientific thought

The existing can be divided into two main categories: interactive proof assistants and textual authoring and publishing tools (including LaTeX, as well as the software that runs the ).

2023 3 5 https://www.forester-notes.org/tfmt-000W/ tfmt-000W /tfmt-000W/ Evergreen notes in the sciences 2022 12 26 https://www.forester-notes.org/tfmt-0003/ tfmt-0003 /tfmt-0003/ Evergreen notes Definition

The phrase evergreen note is due to , who has about it in his . Evergreen notes are permanent notes that evolve and accumulate over time, cutting across different projects.

2022 12 27 https://www.forester-notes.org/tfmt-0007/ tfmt-0007 /tfmt-0007/ Atomicity of scientific notes

One of the design principles for described by is atomicity (): a note should capture just one thing, and if possible, all of that thing. A related point is that it should be possible to understand a note by (1) reading it, and (2) traversing the notes that it links to and recursively understanding those notes.

Traditional mathematical writing does not achieve this kind of atomicity: understanding the meaning of a particular node (e.g. a theorem or definition) usually requires understanding everything that came (textually) before it. In the context of the , this would translate to needing to go upward in the hierarchy in order to understand the meaning of a leaf node. I regard this property of traditional notes as a defect: we should prefer explicit context over implicit context.

High-quality scientific notes should make sense with minimal context; hierarchical context is imposed in order to tell a story, but consumers of scientific notes should not be forced into a particular narrative. Indeed, as many different hierarchical structures can be imposed, many different narratives can be explored.

My first exploration of hypertext science was the ; in hindsight, these lecture notes are very much traditional lecture notes, not written with the atomicity principle in mind. As a result, it is often difficult to understand a given node without ascending upward in the hierarchy.

2022 12 27 https://www.forester-notes.org/tfmt-0008/ tfmt-0008 /tfmt-0008/ Achieving atomicity

in is enhanced by adhering to the following principles:

1. no free variables: do not rely on one-off objects that are defined incidentally upwards in the hierarchy; turn them into atomic nodes that can be linked;
2. favor explicit dependency: whenever using a terminology or construction that has been defined elsewhere, link it;
3. notation should be decodable: all notations (except the most very basic) should be recalled via a link.

It can be a bit excessive to link every word: but the pertinent links could be added to a “related pages” section.

2022 12 26 https://www.forester-notes.org/tfmt-0005/ tfmt-0005 /tfmt-0005/ Hierarchy in evergreen notes

describes a number of organizing principles for , which are quite compelling; one design principle () deserves additional discussion in the context of mathematical thought. In particular, the problem of circular reference must be grappled with immediately rather than incidentally: in ordinary knowledge management, circularity represents the completion of a train of thought, whereas in mathematical thinking it remains very important to distinguish assumptions from consequences.

Hence a purely associative organization of mathematical knowledge is not viable (although it often happens by accident), and so the hierarchical organization of mathematics must be taken seriously from the start. We find that has in fact already grappled with the need for hierarchy in his note , where he discusses the difficulty of traversing the “neighbor”-relationship between notes that are related by another note’s context, but are not related on their own. proposes to solve the problem by grafting hierarchy onto the associative ontology after the fact through “outline notes”:

“Outline notes” can create pseudo-hierarchies with order and structure by linking to many child notes. Then we need the UI to support navigating between neighbors “through” these outline notes.

The viewpoint of outline hierarchy as a structure imposed on the existing associative ontology is a convenient organizing principle for evergreen notes in the sense of , but it is a necessary principle for the design of tools for scientific thought.

2022 12 26 https://www.forester-notes.org/tfmt-0006/ tfmt-0006 /tfmt-0006/ Hierarchical structure as non-unique narrative

Multiple hierarchical structures can be imposed on the same associative network of nodes; a hierarchical structure amounts to a “narrative” that contextualizes a given subgraph of the network. One example could be the construction of lecture notes; another example could be a homework sheet; a further example could be a book chapter or scientific article. Although these may draw from the same body of definitions, theorems, examples, and exercises, these objects are contextualized within a different narrative, often toward fundamentally different ends.

As a result, any interface for navigating the neighbor-relation in hierarchically organized notes would need to take account of the multiplicity of parent nodes. Most hypertext tools assume that the position of a node in the hierarchy is unique, and therefore have a single “next/previous” navigation interface; we must investigate the design of interfaces that surface all parent/neighbor relations.

2022 12 27 https://www.forester-notes.org/tfmt-0009/ tfmt-0009 /tfmt-0009/ The best structure to impose is relatively flat

It is easy to make the mistake of prematurely imposing a complex hierarchical structure on a network of notes, which leads to excessive refactoring. Hierarchy should be used sparingly, and its strength is for the large-scale organization of ideas. The best structure to impose on a network of many small related ideas is a relatively flat one. I believe that this is one of the mistakes made in the writing of the foundations of relative category theory, whose hierarchical nesting was too complex and quite beholden to my experience with pre-hypertext media.

There are many ways to model hierarchy, but there are two salient orthogonal distinctions in the different designs.

2022 12 29 https://www.forester-notes.org/tfmt-000B/ tfmt-000B /tfmt-000B/ Absolute vs. relative hierarchy in document markup languages

Both HTML and LaTeX support a form of hierarchical organization with “absolute” heading levels, i.e. levels that count upward from a single root. In HTML, there is ]]>, ]]>, ]]>..., and in LaTeX there is , , , ,, ..., depending on the document class. This is in contrast to a relative model of hierarchy, in which there is a single command to introduce a section heading at the “current” level, and there are other commands to introduce hierarchical nesting.

The absolute sectioning model is completely inadequate for the hierarchical organization of ideas, for the simple reason that it is the context of a node that determines what its level in the hierarchy is, not the node itself. When this is mixed up, it makes re-contextualization an extremely painful and time-consuming process: you must recursively increment or decrement all section levels that occur underneath a given node, as anyone who has used LaTeX for any significant writing project can attest.

In traditional texts, re-contextualization occurs when you want to move a section from one place in the hierarchy to another; in the more fluid media I am pursuing, there may be imposed on the network, so re-contextualization ceases to be a refactoring task and is elevated as a . In either case, we are drawn to prefer relative hierarchy over absolute hierarchy. See .

This is similar to the relationship between De Bruijn levels (global levels) and De Bruijn indices (local levels) in type theory: conventional section headings are like De Bruijn indices in that they count from the root node, whereas what we would want are section headings that count from the present node.

2022 12 29 https://www.forester-notes.org/tfmt-000D/ tfmt-000D /tfmt-000D/ Implicit vs. explicit hierarchy in document markup languages

Many document markup languages, including LaTeX and HTML, use sectioning commands that evince an implicit hierarchical structure: for instance, consider the following HTML code:

Foo

Bar

Baz

Qux ]]>

The above corresponds to the tree [Bar > [Baz, Qux]], Boo]]]>. On the other hand, it is also possible to consider a model in which the hierarchy is made explicit through the syntactical tree structure of the markup language. This style is also supported (but not forced) in HTML:

Bar

Baz

Qux

]]>

We greatly prefer the combination of (relative, explicit) hierarchy.

2022 12 29 https://www.forester-notes.org/tfmt-000C/ tfmt-000C /tfmt-000C/ Relative hierarchy in existing tools

There are a few LaTeX packages that implement relative hierarchy for sectioning as an alternative to the .

• The package implements relative sectioning commands; similar to the existing sectioning commands, an model is employed, leading to an imperative feel with commands like }]]> and }]]>.
• The package builds on to behave better under the transclusion of LaTeX documents, introducing a command that is to be used instead of or .
• On the other hand, the package implements a form of relative sectioning with an , i.e. one in which the syntactical nesting of LaTeX environments induces the hierarchy.

There are some attempts to impose a (, ) hierarchical model in HTML by using ]]> and only the ]]> heading command. In the HTML5 spec, this behavior was initially endorsed as part of the “outline” algorithm, but unfortunately .

2023 3 4 https://www.forester-notes.org/tfmt-000V/ tfmt-000V /tfmt-000V/ Forests of evergreen notes 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition

A forest of (or a forest for short) is loosely defined to be a collection of in which multiple are allowed to emerge and evolve over time. Concretely, one note may contextualize several other notes via transclusion within its textual structure; in the context of a forest, we refer to an individual note as a tree. Of course, a tree can be viewed as a forest that has a root node.

2023 3 4 https://www.forester-notes.org/tfmt-000U/ tfmt-000U /tfmt-000U/ The extent of a tree in a forest Definition

The extent of a is the smallest set of trees closed under the following rules:

1. lies within the extent of .
2. If is transcluded by , then any tree in the extent of lies also in the extent of .

2023 3 4 https://www.forester-notes.org/tfmt-000Q/ tfmt-000Q /tfmt-000Q/ Authorship and responsibility in forests

A may in general contain the work of many authors who have contributed in different ways. However, the correct attribution of authorship to a given tree is more subtle than one might at first think.

To understand this subtlety, we first consider that each individual tree may contain both textual content and transcluded subtrees. Thinking inductively, a simple model of tree authorship would be to take the union of the authors of the immediate textual content and the authors of all trees within its . This model is incorrect, however, as authorship is usually taken to imply responsibility and endorsement, as can be seen by way of example from the :

They agree to be held accountable for any issues relating to the correctness or integrity of the work with the understanding that depending on the circumstances not all authors are necessarily held “equally” accountable. In the case of publications-related misconduct, it may be the case that penalties may vary for co-authors listed on a single publication.

In particular, although one person may be aware of and responsible for the content of a given tree, it would be unreasonable to require them to be responsible for any subsequent (and potentially erroneous!) re-contextualization of that tree in the forest. For this reason, must be distinguished from in .

2023 3 4 https://www.forester-notes.org/tfmt-000S/ tfmt-000S /tfmt-000S/ Author of a tree Definition

An author of a is someone who satisfies the following conditions:

1. They contributed intellectually to the immediate textual content of the tree, i.e. the non-transcluded content.
2. They can be held responsible for all the content within the tree, i.e. both the immediate textual content as well as the content of all the subtrees.

2023 3 4 https://www.forester-notes.org/tfmt-000T/ tfmt-000T /tfmt-000T/ Contributor to a tree Definition

A direct contributor to a is either an of the tree, or has contributed intellectually to the immediate content of the tree but cannot be held responsible for it.

A contributor to a tree is someone who is a direct contributor to at least one tree lying within its .

2023 1 7 https://www.forester-notes.org/tfmt-000E/ tfmt-000E /tfmt-000E/ Requirements for typesetting mathematics

Many non-LaTeX hypertext tools boast some compatibility with mathematical typesetting: for instance, in any HTML-based tool it is possible to use MathML or, for better cross-browser support and easier authoring, import or . For instance: , , and all support rendering of LaTeX math code using either or MathJax. Unfortunately, the “support” provided is so limited that it is not usable for a working mathematician — so it is somewhat puzzling why the support is present in the first place. Here we will discuss some fundamental requirements for any tool that aims to support mathematical notes, without which it is not applicable for use by professionals.

2023 1 7 https://www.forester-notes.org/tfmt-000F/ tfmt-000F /tfmt-000F/ Notational macros in mathematical authoring

Mathematical writing tends to involve a variety of notations which (1) can be difficult to typeset by hand, and (2) will likely change over time. The difficulty of hand-typesetting is somewhat less important than the propensity of notation to change over time: when we change notations within a given mathematical work, we must update every occurrence of the notation: but when the representation of the notation is unstructured, it is not in fact possible for a tool (e.g. find-and-replace) to detect every instance that needs to be updated. Therefore, it is mandatory that the representation of mathematical notations be structured.

LaTeX allows authors to structure their notations very simply using macros, which can be introduced using or . It is trivial to update all occurences of a notation by simply changing the definition of the corresponding macro.

Unfortunately, most tools that purport to support the inclusion of mathematical expressions do not have adequate support for macros. Both and have excellent support for configuring macros, but these configuration options are not available in most of the tools that build on and MathJax: for instance, and and all support embedding mathematics, but they do not support configuring macros. In fact there is a community plugin for Obsidian that adds this functionality, but it only supports imposing a global macro library on the entire “vault”, which is .

2023 1 7 https://www.forester-notes.org/tfmt-000H/ tfmt-000H /tfmt-000H/ Notational macros are local, not global

In LaTeX, macros are organized into packages that are then globally imported into a single document. Because a LaTeX document comprises just one project and thus any transclusions (via or ) are of components local to that one project, this model is adequate — although experienced users of LaTeX are nonetheless all too aware of the difficulties of namespacing macro commands when interacting with multiple packages or document classes.

The requirements for a that aims to bring together multiple projects over a very long period of time are somewhat different: many distinct packages of notation will be used across the body of work, and it is not possible to fix a single global notation package.

Indeed, it is not reasonable to expect that all notes within a person’s mathematical life shall share the same notations, and in many cases, it would moreover be necessary for the names of the macros associated to these notations to clash. This can happen because two projects are orthogonal, or it can happen as the author’s tastes change over time — and it is not reasonable for such a tool to force enormous and weighty refactorings (touching thousands or tens of thousands of notes) every time the author’s taste changes. The need for arduous refactorings of this kind is one of the main ways that large mathematical projects tend to collapse under their own weight.

It follows that any whose support for mathematical notations involves a globally-defined macro package is inadequate for mathematical uses. On the other hand, it is also not reasonable to require the author to define all their macros in each note: notes tend to be small, and there will always be large clusters of notes that share the same notations — and for which the small refactoring tasks involved when notations change are a positive feature rather than a negative one, as one of the goals of a cluster is to accumulate cohesion.

Therefore, the precise requirement for macro library support is as follows:

1. The author must be able to define (in their own files) multiple notational macro libraries.
2. A given note must be able to specify which macro libraries (if any) it employs.

Finally, careful attention must be paid to the interaction between the above requirements and the transclusion of mathematical notes: a transcluded note must be rendered with respect to its own macro library, and not that of the parent note.

2023 1 7 https://www.forester-notes.org/tfmt-000G/ tfmt-000G /tfmt-000G/ Mathematical diagrams and macro support

A basic requirement of is to support the rendering of mathematical diagrams. What kinds of diagrams are needed depends, of course, on the problem domain: for my own work, the main diagram-forms needed are commutative diagrams and string diagrams.

2023 1 7 https://www.forester-notes.org/tfmt-000P/ tfmt-000P /tfmt-000P/ Mathematical expressions and diagrams are tightly coupled

Although diagramming may seem to non-mathematicians to be somewhat orthogonal to notational macro support, in reality any solution to the diagramming problem must be tightly and natively integrated with the rendering of mathematical expressions — simply because most diagrams involve mathematical expressions, and these invariably involve notational macros. The reason PGF/TikZ has been so successful is that it respects this tight coupling.

The situation for hypertext mathematical tools is somewhat less advanced than that of LaTeX and PFG/TikZ, but there are several options which we discuss below.

2023 1 7 https://www.forester-notes.org/tfmt-000J/ tfmt-000J /tfmt-000J/ Commutative diagrams in KaTeX

has a very rudimentary support for commutative diagrams built-in, by emulating the package. Unfortunately, this support is completely inadequate for usage by mathematicians today:

1. Only square diagram shapes are supported: commutative diagrams in general have diagonal and curved lines, but these are not supported.
2. The rendering of the limited gamut of supported commutative diagrams is broken in most browsers (at least Safari and Firefox). In particular, lines are jagged as they are pieced together from pipes and arrows that are subtly misaligned.

2023 1 7 https://www.forester-notes.org/tfmt-000K/ tfmt-000K /tfmt-000K/ Commutative diagrams in MathJax

Like , supports the commands for rudimentary square-shaped commutative diagrams. Unlike the of , the supported diagrams are rendered correctly without jagged lines; this means that for the vanishingly small population of mathematicians whose needs are limited to square-shaped diagrams, MathJax’s builtin support is viable.

On the other hand, there is a more advanced option available for users of MathJax: the , which adds support for the full gamut of diagrams to MathJax. Notably, this plugin is used by the . The only downside of the support is that it interacts poorly with accessibility features (but no worse than any other solution to rendering non-trivial commutative diagrams), and diagrams created using look considerably less professional than those created using or .

Both and have the benefit that diagrams created using them will respect the ambient macro package with which the tool has been configured; therefore, if one looks past the rudimentary nature of the support for commutative diagrams, our main requirement is indeed satisfied. Another tool worth discussing is .

2023 1 7 https://www.forester-notes.org/tfmt-000I/ tfmt-000I /tfmt-000I/ The quiver interactive diagramming tool

The application is an excellent graphical interface for interactively constructing commutative diagrams, with very high-quality rendering.

One positive aspect of quiver is that it is possible to load it with , so that diagrams involving custom notations render correctly in the graphical interface. The downside of the approach here is that the macro library must be located on a publicly accessible URL that can be pasted into the quiver interface.

Quiver also offers excellent support for embedding the resulting diagrams in existing LaTeX documents: after creating your diagram, you can request a LaTeX snippet that includes a URL which allows you to resume editing your diagram. For example, the following code corresponds to the URL https://q.uiver.app/?q=WzAsMixbMCwwLCJBIl0sWzEsMCwiQiJdLFswLDFdXQ==:

Unfortunately, the support for embedding quiver diagrams in HTML documents is currently inadequate for professional use. The HTML embed code provided simply produces an ]]>, and it is not possible to style the interior of the embedded frame (e.g. to change the background color, or decrease the margins):

]]>

Therefore, we must conclude that although quiver is an excellent tool for authors of traditional LaTeX documents, it is not currently a candidate for inclusion in tools for hypertext mathematical authoring.

Because of the currently for embedding diagrams in hypertext settings, we cannot consider it any further. There is a final option that turns out to be the most used in practice: generating SVG images statically from embedded LaTeX code.

2023 1 7 https://www.forester-notes.org/tfmt-000L/ tfmt-000L /tfmt-000L/ Generating images statically using LaTeX

Because of the the other available tools, most authors of hypertext mathematics with diagramming needs tend to rely on the static generation of images from LaTeX code using a local LaTeX toolchain. It is not difficult to instrument with a .

There are also a variety of other tools that do something similar, which tend to be employed in static site generation:

• by is used by as well as , both via .
• by is used by the present web site.

The basic architecture of such a tool is to scan for LaTeX blocks, and then identify them by a hash of their contents. This hash is used as a filename for files, which are compiled to and thence to using the tool; the resulting file is then embedded in HTML using an ]]> tag. Alternatively, is also possible to transclude the resulting ]]> element directly, but then , as it is possible for two different ]]> elements on a single page to interfere one each other.

Both and support passing a macro library to be used when rendering. Both and set their macro libraries on a page-local basis.

A serious downside of generating images from LaTeX code is the negative impact on accessibility tools. This seems only slightly mitigated by the transclusion of the ]]> element as opposed to using ]]>. Ultimately accessibility for mathematical diagrams remains an unsolved problem, and it does not seem that the existing discussion on accessibility of hypertext mathematics has much to say about this problem.

Finally, we comment on more principled approaches using web standards such as SVG and MathML that we hope will take form in the future.

2023 1 7 https://www.forester-notes.org/tfmt-000N/ tfmt-000N /tfmt-000N/ SVG is not an authoring language

SVG is an extremely powerful low-level language for vector images and diagrams with a variety of applications. Unfortunately, it is not reasonable to compose such diagrams directly in SVG as an author: in contrast to programmatic tools like PGF/TikZ, all positions in SVG are fixed, and there is no possibility to impose important abstractions (e.g. the concept of a line that is “glued” to a pair of nodes). On the other hand, there are many advantages to SVG, including the possibility to .

Because of the low level of abstraction, SVG images that appear in practice today are nearly always produced by a tool or compiler from an input that is defined at a much higher level of abstraction.

2023 1 7 https://www.forester-notes.org/tfmt-000O/ tfmt-000O /tfmt-000O/ MathML is not an authoring language

Despite some preliminary support for structured representation of high-level mathematical idioms via , MathML is not intended to be an authoring language: it is a target language for other tools. Moreover, the content dictionaries (collections of basic elements) of Content MathML are chosen to pertain to the needs of grade-school and secondary-school mathematics and not at all to the needs of professional mathematics:

The base set of content elements is chosen to be adequate for simple coding of most of the formulas used from kindergarten to the end of high school in the United States, and probably beyond through the first two years of college, that is up to A-Level or Baccalaureate level in Europe.

Nonetheless, it seems that the goal was for the content dictionaries of Content MathML to be extended by the individual “communities of practice” to meet their specific needs:

Hence, it is not in general possible for a user agent to automatically determine the proper interpretation for values without further information about the context and community of practice in which the MathML instance occurs.

However, in contexts where highly precise semantics are required (e.g. communication between computer algebra systems, within formal systems such as theorem provers, etc.) it is the responsibility of the relevant community of practice to verify, extend or replace definitions provided by OpenMath CDs as appropriate.

It seems that there is a possibility to define your own semantic notational macros, and this certainly bears further investigation. Due to the mutually reinforcing combination of historically poor vendor support and near-absolute isolation from actual communities of practice, i.e. working mathematicians, sophisticated direct use of MathML has never caught on. On the other hand, there is a great deal of MathML on the web today in the form of and output — tools which are not only currently necessary for obtaining consistent (and professional-quality) rendering of mathematics across browsers, but also are necessary for authoring due to their more succinct markup and easy support for macros.

It seems that the future of MathML is brighter than it was in the past, as we are finally seeing a vital project to improve vendor support led by . Currently, even browsers that support the MathML standard do so with completely inadequate and unprofessional rendering quality, which means that tools like MathJax and may remain necessary for some time even after vendors finally support MathML. But we hope that with improved vendor support comes new and productive experiments with using semantic tools like XSLT to handle macros, etc. Unfortunately, given the , this transformation will not take place unless high-level hypertext-compatible tools for drawing diagrams are simultaneously developed.

2023 1 7 https://www.forester-notes.org/tfmt-000M/ tfmt-000M /tfmt-000M/ Towards mixing SVG and MathML in hypertext mathematics

The points out that MathML can be embedded into ]]> elements using the ]]> element. This is a great strength of the modularity of the model, and I believe that in the future, we will be able to use this as a way to render accessible mathematical diagrams in hypertext.

What is missing? Essentially the current issue preventing widespread use of this method is the fact that neither SVG nor MathML is an authoring language: they are to be seriously used by authors.

For exactly so long as diagrams must be drawn using LaTeX-based tools rather than something MathML-compatible, it would be non-negotiable for the support of notational macros to itself be based in LaTeX syntax (e.g. as in both and MathJax). But it is worth imagining a future in which mathematical diagrams are drawn using a high-level interface to SVG, and then a pure MathML approach to notational macros becomes quite viable. This is not currently the world we live in, but it is something to hope for.