https://www.forester-notes.org/tfmt-0001/index.xml Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0001/ tfmt-0001 /tfmt-0001/ 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. Jon Sterling 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 evergreen notes. 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. Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0004/ tfmt-0004 /tfmt-0004/ Existing tools for scientific thought The existing tools for scientific thought can be divided into two main categories: interactive proof assistants and textual authoring and publishing tools (including LaTeX, as well as the Gerby software that runs the Stacks Project). Jon Sterling 2023 3 5 https://www.forester-notes.org/tfmt-000W/ tfmt-000W /tfmt-000W/ Evergreen notes in the sciences Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0003/ tfmt-0003 /tfmt-0003/ Evergreen notes Definition The phrase evergreen note is due to Andy Matuschak, who has written extensively about it in his public Zettelkasten. Evergreen notes are permanent notes that evolve and accumulate over time, cutting across different projects. Jon Sterling 2022 12 27 https://www.forester-notes.org/tfmt-0007/ tfmt-0007 /tfmt-0007/ Atomicity of scientific notes One of the design principles for evergreen notes described by Matuschak is atomicity (Evergreen notes should be atomic): 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 hierarchical organization of evergreen notes, 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 lecture notes on relative category theory; 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. Jon Sterling 2022 12 27 https://www.forester-notes.org/tfmt-0008/ tfmt-0008 /tfmt-0008/ Achieving atomicity Atomicity in evergreen notes is enhanced by adhering to the following principles: 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; favor explicit dependency: whenever using a terminology or construction that has been defined elsewhere, link it; 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. Jon Sterling 2022 12 26 https://www.forester-notes.org/tfmt-0005/ tfmt-0005 /tfmt-0005/ Hierarchy in evergreen notes Matuschak describes a number of organizing principles for evergreen notes, which are quite compelling; one design principle (Prefer associative ontologies to hierarchical taxonomies) 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 assump tions 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 Matuschak has in fact already grappled with the need for hierarchy in his note It's hard to navigate to unlinked "neighbors" in associative note systems, 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. Matuschak 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 Matuschak, but it is a necessary principle for the design of tools for scientific thought. Jon Sterling 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. Jon Sterling 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. Jon Sterling 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 many orthogonal hierarchical structures imposed on the network, so re-contextualization ceases to be a refactoring task and is elevated as a basic unit of scientific activity. In either case, we are drawn to prefer relative hierarchy over absolute hierarchy. See existing implementations of this idea. 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. Jon Sterling 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

Boo

]]> 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:

Foo

Bar

Baz

Qux

Boo

]]> We greatly prefer the combination of (relative, explicit) hierarchy. Jon Sterling 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 backward model of absolute hierarchy. The coseoul package implements relative sectioning commands; similar to the existing sectioning commands, an implicit hierarchy model is employed, leading to an imperative feel with commands like }]]> and }]]>. The modular package builds on coseoul 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 dieudonne package implements a form of relative sectioning with an explicit hierarchical model, i.e. one in which the syntactical nesting of LaTeX environments induces the hierarchy. There are some attempts to impose a (relative, explicit) 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 almost no vendors of browsers nor assistive technology have correctly implemented this behavior. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000V/ tfmt-000V /tfmt-000V/ Forests of evergreen notes Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition A forest of evergreen notes (or a forest for short) is loosely defined to be a collection of evergreen notes in which multiple hierarchical structures 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. Jon Sterling 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 tree within a forest is the smallest set of trees closed under the following rules: lies within the extent of . If is transcluded by , then any tree in the extent of lies also in the extent of . Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000Q/ tfmt-000Q /tfmt-000Q/ Authorship and responsibility in forests A forest of evergreen notes 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 extent. 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 ACM Policy on Authorship, Peer Review, Readership, and Conference Publication: 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, authors must be distinguished from contributors in forests of evergreen notes. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000S/ tfmt-000S /tfmt-000S/ Author of a tree Definition An author of a tree within a forest is someone who satisfies the following conditions: They contributed intellectually to the immediate textual content of the tree, i.e. the non-transcluded content. 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. Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000T/ tfmt-000T /tfmt-000T/ Contributor to a tree Definition A direct contributor to a tree within a forest is either an author 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 extent. Jon Sterling 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 MathJax. For instance: Logseq, Obsidian, and Notion 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 fundament al requirements for any tool that aims to support mathematical notes, without which it is not applicable for use by professionals. Jon Sterling 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 MathJax 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, Logseq and Obsidian and Notion 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", whi ch is inadequate. Jon Sterling 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 tool 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 tool for thought 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: The author must be able to define (in their own files) multiple notational macro libraries. 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. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000G/ tfmt-000G /tfmt-000G/ Mathematical diagrams and macro support A basic requirement of tools for scientific thought 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. Jon Sterling 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. Jon Sterling 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: Only square diagram shapes are supported: commutative diagrams in general have diagonal and curved lines, but these are not supported. 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. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000K/ tfmt-000K /tfmt-000K/ Commutative diagrams in MathJax Like , MathJax supports the commands for rudimentary square-shaped commutative diagrams. Unlike the implementation 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 XyJax-v3 plugin, which adds support for the full gamut of diagrams to MathJax. Notably, this plugin is used by the Stacks Project. 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 quiver. Both and MathJax 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 quiver. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000I/ tfmt-000I /tfmt-000I/ The quiver interactive diagramming tool The quiver 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 your own macro library, 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 inadequate support of quiver 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. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000L/ tfmt-000L /tfmt-000L/ Generating images statically using LaTeX Because of the general inadequacy of 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 pandoc with a Lua filter to render tikz code to SVG images. There are also a variety of other tools that do something similar, which tend to be employed in static site generation: antex by Paolo Brasolin is used by Krater as well as jekyll-sheafy, both via jekyll-antex. Forester by Jonathan Sterling 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 one must be careful to rename all identifiers in the ]]> element uniquely, as it is possible for two different ]]> elements on a single page to interfere one each other. Both antex and Forester support passing a macro library to be used when rendering. Both jekyll-sheafy and Forester 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. Jon Sterling 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 intermix SVG with other formats such as MathML. 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. Jon Sterling 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 Content MathML, 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 use XSLT 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 MathJax 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 m ore 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 Igalia. 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 tight coupling between the authoring of mathematical expressions and of mathematical diagrams, this transformation will not take place unless high-level hypertext-compatible tools for drawing diagrams are simultaneously developed. Jon Sterling 2023 1 7 https://www.forester-notes.org/tfmt-000M/ tfmt-000M /tfmt-000M/ Towards mixing SVG and MathML in hypertext mathematics The W3C MathML Core Working Draft 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 both currently too low-level 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. References The Stacks Project Authors 2018 https://www.forester-notes.org/stacks-project/ stacks-project /stacks-project/ The Stacks project Reference https://stacks.math.columbia.edu The Stacks project is an ever growing open source textbook and reference work on algebraic stacks and the algebraic geometry needed to define them. Here are some quick facts: The Stacks project is not an introductory text. It is written for graduate students and researchers in algebraic geometry. The aim is to build algebraic geometry and use this in laying the foundations for algebraic stacks. The theory of commutative algebra, schemes, varieties, and algebraic spaces forms an integral part of the Stacks project. The Stacks project has a maintainer (currently Aise Johan de Jong) who accepts changes etc. proposed by contributors. Everyone is encouraged to participate. The Stacks project is meant to be read online. Consequently we do not worry about length of the chapters, etc. With hyperlinks and the search function it is possible to quickly browse through the chapters to find the lemmas, theorems, etc. that a given result depends on. We use tags to identify results, which are permanent identifiers for a result. You can read more about this on the tags explained page. For a longer discussion, please read the blog post What is the stacks project?. Pieter Belmans Raymond Cheng Aise Johan de Jong https://www.forester-notes.org/gerby/ gerby /gerby/ Gerby Reference https://gerby-project.github.io/ If you have a LaTeX document which is large (probably several hundreds of pages at least) is regularly updated needs to be externally referenced often you will run into the problem that large PDFs are not easily navigable PDFs of any size are not very searchable the internal numbering changes often, making external references outdated Gerby addresses these problems by providing an online tag-based view, instead of just having a big PDF. Gerby is tailored towards making large online textbooks and reference works more accessible. In case you were wondering, a gerbe is a kind of stack (in the mathematical sense), and the software was originally meant for the Stacks project. Context Backlinks Jon Sterling 2023 8 15 https://www.forester-notes.org/007L/ 007L /007L/ Bottom-up hierarchy via transclusion You may be used to writing documents, where you work from the top down: you create some section headings, put some text under those headings, make some deeper section headings, put more text, etc. Forests work in the opposite way, from the bottom up: you start by writing independent, atomic notes/trees and then only later start to (sparingly) assemble these into a hierarchy in order to reify the emerging structure. Forester's bottom-up approach to section hierarchy works via something called transclusion. The idea is that at any time, you can include ("transclude") the full contents of another tree into the current tree as a subsection by adding the following code: This is kind of like 's command, but much better behaved: for instance, section levels are computed on the fly depending on the position in the hierarchy. This entire tutorial is cobbled together by transcluding many smaller trees, each with their own independent existence. For example, the following two sections are transcluded from an entirely different part of my forest: Jon Sterling 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. One of the immediate impacts and strengths of Forester's transclusion model is that a given tree has no canonical "geographic" location in the forest. One tree can appear as a child of many other trees, which allows the same content to be incorporated into different textual and intellectual narratives. Jon Sterling 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. Jon Sterling 2023 5 14 https://www.forester-notes.org/0053/ 0053 /0053/ Introducing Forester: a tool for scientific thought After spending two years exploring the design of tools for scientific thought that meet the unique needs of real, scalable scientific writing in hypertext, I have created a tool called Forester which has the following benefits: Forester is tag-based like Gerby, and can therefore power large-scale generational projects like Stacks and Kerodon. Forester produces static content that can be uploaded to any web hosting service without needing to run or install any serverside software. Forester is easy to install on your own machine. To prevent bitrot, Forester is a single tool rather than a composition of several tools. Forester satisfies all the requirements of serious scientific writing, including sophisticated notational macros, typesetting of diagrams, etc. Forester combines associative and hierarchical networks of evergreen notes (called "trees") into hypertext sites called "forests". Jon Sterling 2023 3 4 https://www.forester-notes.org/tfmt-000R/ tfmt-000R /tfmt-000R/ Forests and trees of evergreen notes Definition A forest of evergreen notes (or a forest for short) is loosely defined to be a collection of evergreen notes in which multiple hierarchical structures 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. Trees correspond roughly to what are referred to as "tags" in the Stacks Project. Related Contributions