table-of-contents, reference order

24 files changed, 256 insertions, 177 deletions

diff --git a/root/articles/mmmfs/$order b/root/articles/mmmfs/$order
index 10dcf5c..563d544 100644
--- a/root/articles/mmmfs/$order
+++ b/root/articles/mmmfs/$order
@@ -1,5 +1,6 @@
 title
 abstract
+table-of-contents
 motivation
 historical-approaches
 framework
@@ -8,5 +9,5 @@ examples
 evaluation
 conclusion
 references
-statement-of-originality
 ba_log
+statement-of-originality
diff --git a/root/articles/mmmfs/ba_log/intro: text$markdown.md b/root/articles/mmmfs/ba_log/intro: text$markdown.md
new file mode 100644
index 0000000..37366cf
--- /dev/null
+++ b/root/articles/mmmfs/ba_log/intro: text$markdown.md
@@ -0,0 +1,4 @@
+The following pages document the development of the `mmmfs` system described above in the form of a project log.
+Please note that the log has been written primarily for viewing using a web browser, and as such makes extensive use of
+hyperlinking, and also includes some videos that cannot be reproduced in print. It is therefore recommended to view the
+live version of the log online at the following address: [s-ol.nu/ba/log](https://s-ol.nu/ba/log).
diff --git a/root/articles/mmmfs/ba_log/print: text$moonscript -> fn -> mmm$dom.moon b/root/articles/mmmfs/ba_log/print: text$moonscript -> fn -> mmm$dom.moon
index d23edbb..97a6283 100644
--- a/root/articles/mmmfs/ba_log/print: text$moonscript -> fn -> mmm$dom.moon
+++ b/root/articles/mmmfs/ba_log/print: text$moonscript -> fn -> mmm$dom.moon
@@ -6,7 +6,8 @@ import ropairs from require 'mmm.ordered'
   div {
     class: 'print-ownpage'
 
-    h1 link_to @, "appendix: project log"
+    h1 (link_to @, "appendix: project log"), id: 'ba-log'
+    @gett 'intro: mmm/dom'
     table.unpack for post in *@children
       continue if post\get 'hidden: bool'
 
diff --git a/root/articles/mmmfs/ba_log/text$moonscript -> fn -> mmm$dom.moon b/root/articles/mmmfs/ba_log/text$moonscript -> fn -> mmm$dom.moon
index 37ffc78..bd2859d 100644
--- a/root/articles/mmmfs/ba_log/text$moonscript -> fn -> mmm$dom.moon
+++ b/root/articles/mmmfs/ba_log/text$moonscript -> fn -> mmm$dom.moon
@@ -4,7 +4,8 @@ import ropairs from require 'mmm.ordered'
 
 =>
   div {
-    h1 link_to @, "appendix: project log"
+    h1 (link_to @, "appendix: project log"), id: 'ba-log'
+    @gett 'intro: mmm/dom'
     ul do
       posts = for post in *@children
         continue if post\get 'hidden: bool'
diff --git a/root/articles/mmmfs/ba_log/title: text$plain b/root/articles/mmmfs/ba_log/title: text$plain
deleted file mode 100644
index a440bf3..0000000
--- a/root/articles/mmmfs/ba_log/title: text$plain
+++ /dev/null
@@ -1 +0,0 @@
-project log
diff --git a/root/articles/mmmfs/conclusion/text$markdown+sidenotes.md b/root/articles/mmmfs/conclusion/text$markdown+sidenotes.md
index 45d3bdf..0780b23 100644
--- a/root/articles/mmmfs/conclusion/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/conclusion/text$markdown+sidenotes.md
@@ -1,4 +1,3 @@
-conclusion
-==========
+# 7. conclusion
 
 <div class="well well-warning">[section under construction]</div>
diff --git a/root/articles/mmmfs/evaluation/text$markdown+sidenotes.md b/root/articles/mmmfs/evaluation/text$markdown+sidenotes.md
index 1c8fda7..70b8df5 100644
--- a/root/articles/mmmfs/evaluation/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/evaluation/text$markdown+sidenotes.md
@@ -1,11 +1,10 @@
-evaluation
-==========
+# 6. evaluation
 
-## examples
+## 6.1 examples
 In this section I will take a look at the implementations of the example for the use cases outlined above,
 and evaluate them with regard to the framework derived in the corresponding section above.
 
-### publishing and blogging
+### 6.1.1 publishing and blogging
 Since mmmfs has grown out of the need for a versatile CMS for a personal publishing website, it is not surprising to
 see that it is still up to that job. Nevertheless it is worth taking a look at its strengths and weaknesses in this
 context:
@@ -25,7 +24,7 @@ Another issue is that the system is currently based on the presumption that cont
 separately from its parent and context in most cases. This has made the implementation of sidenotes less idiomatic
 than initially anticipated.
 
-### pinwall
+### 6.1.2 pinwall
 The pinwall example shows some strenghts of the mmmfs system pretty convincingly.
 The type coercion layer completely abstracts away the complexities of transcluding different types of content,
 and only positioning and sizing the content, as well as enabling interaction, remain to handle in the pinwall fileder.
@@ -40,7 +39,7 @@ take care of capturing and handling JS events. The bulk of complexity is therefo
 UI layer (in this case the browser), which could feasibly be simplified through a custom abstraction layer or the use of
 output means other than the web.
 
-### slideshow
+### 6.1.3 slideshow
 A simplified image slideshow example consists of only 20 lines of code and demonstrates how the reactive component
 framework simplifies the generation of ad-hoc UI dramatically:
 
@@ -71,13 +70,13 @@ such as the fullscreen API and sizing content proportionally to the viewport siz
 The parts of the code dealing with the content are essentially identical, except that content is transcluded via the
 more general `mmm/dom` type-interface, allowing for a greater variety of types of content to be used as slides.
 
-## general concerns
+## 6.2 general concerns
 While the system has proven pretty successful and moldable to the different use-cases that it has been tested in,
 there are also limitations in the proposed system that have become obvious in developing and working with the system.
 Some of these have been anticipated for some time and concrete research directions for solutions are apparent,
 while others may be intrinsic limitations in the approach taken.
 
-### global set of converts
+### 6.2.1 global set of converts
 In the current system, there is only a single, global set of *converts* that can be potentially applied to facets
 anywhere in the system.
 Therefore it is necessary to encode behaviour directly (as code) in facets wherever exceptional behaviour is required.
@@ -98,7 +97,7 @@ further up in the tree, for example to specialize types based on their context i
 The biggest downside to this approach would be that it  presents another pressure factor for, while also reincforcing,
 the hierarchical organization of data, thereby exacerbating the limits of hierarchical structures.
 
-### code outside of the system
+### 6.2.2 code outside of the system
 At the moment, a large part of the mmmfs codebase is still separate from the content, and developed outside of mmmfs
 itself. This is a result of the development process of mmmfs and was necessary to start the project as the filesystem
 itself matured, but has now become a limitation of the user experience: potential users of mmmfs would generally start
@@ -115,7 +114,7 @@ for the global set of *converts* (see above), as well as the layout used to rend
 Both of these are expected to undergo changes as users adapt the system to their own content types and
 domains of interest, as well as their visual identity, respectively.
 
-### type system
+### 6.2.3 type system
 The currently used type system based on strings and pattern matching has been largely satisfactory,
 but has proven problematic for some anticipated use cases.
 It should be considered to switch to a more intricate,
@@ -127,7 +126,7 @@ but others could use this information to generate lower-resolution 'thumbnails'
 Using these mechanisms for example images could be requested with a maximum-resolution constraint to save on bandwidth
 when embedded in other documents.
 
-### type-coercion
+### 6.2.4 type-coercion
 By giving the system more information about the data it is dealing with,
 and then relying on the system to automatically transform between data-types,
 it is easy to lose track of which format data is concretely stored in.
@@ -142,7 +141,7 @@ as well as making this display interactive to encourage experimentation with cus
 Emphasising the conversion process more strongly in this way might be a way to turn this feature from an opaque
 hindrance into a transparent tool. This should represent a challenge mostly in terms of UX and UI design.
 
-### editing
+### 6.2.5 in-system editing
 Because many *converts* are not necessarily reversible, it is very hard to implement generic ways of editing stored data
 in the same format it is viewed. For example, the system trivially converts markdown-formatted text sources into
 viewable HTML markup, but it is hardly possible to propagate changes to the viewable HTML back to the markdown source.
diff --git a/root/articles/mmmfs/examples/implementation: text$markdown+sidenotes.md b/root/articles/mmmfs/examples/implementation: text$markdown+sidenotes.md
new file mode 100644
index 0000000..d32b0db
--- /dev/null
+++ b/root/articles/mmmfs/examples/implementation: text$markdown+sidenotes.md
@@ -0,0 +1,88 @@
+## 5.1 publishing and blogging
+### 5.1.1 blogging
+Blogging is pretty straightforward, since it generally just involves publishing lightly-formatted text,
+interspersed with media such as images and videos or perhaps social media posts.
+Markdown is a great tool for this job, and has been integrated in the system to much success:
+There are two different types registered with *converts*: `text/markdown` and `text/markdown+span`.
+They both render to HTML (and DOM nodes), so they are immediately viewable as part of the system.
+The only difference for `text/markdown+span` is that it is limited to a single line,
+and doesn't render as a paragraph but rather just a line of text.
+This makes it suitable for denoting formatted-text titles and other small strings of text. 
+
+The problem of embedding other content together with text comfortably is also solved easily,
+because Markdown allows embedding arbitrary HTML in the document.
+This made it possible to define a set of pseudo-HTML elements in the Markdown-convert,
+`<mmm-embed>` and `<mmm-link>`, which respectively embed and link to other content native to mmm.
+
+### 5.1.2 scientific publishing
+<div class="sidenote" style="margin-top: 1.25rem">
+One of the 'standard' solutions, <a href="https://www.latex-project.org/">LaTeX</a>,
+is arguably at least as complex as the mmm system proposed here, but has a much narrower scope,
+since it does not support interaction.
+</div>
+
+Scientific publishing is notoriously complex, involving not only the transclusion of diagrams
+and other media, but generally requiring precise and consistent control over formatting and layout.
+Some of these complexities are tedious to manage, but present good opportunities for programmatic
+systems and media to do work for the writer.
+
+One such topic is the topic of references.
+References appear in various formats at multiple positions in a scientific document;
+usually they are referenced via a reduced visual form within the text of the document,
+and then shown again with full details at the end of the document.
+
+For the sake of this thesis, referencing has been implemented using a subset of the popular
+BibTeX format for describing citations. Converts have been implemented for the `text/bibtex`
+type to convert to a full reference format (to `mmm/dom`) and to an inline side-note reference
+(`mmm/dom+link`) that can be transcluded using the `<mmm-link>` pseudo-tag.
+
+For convenience, a convert from the `URL -> cite/acm` type has been provided to `URL -> text/bibtex`,
+which generates links to the ACM Digital Library<mmm-embed path="../references/acm-dl" wrap="sidenote"></mmm-embed>
+API for accessing BibTeX citations for documents in the library. This means that it is enough to store the link to the
+ACM DL entry in mmmfs, and the reference will automatically be fetched, and therefore stay up to date with potential
+remote corrections.
+
+## 5.2 pinwall
+In many situations, in particular for creative work, it is often useful to compile resources of
+different types for reference or inspiration, and arrange them spacially so that they can be viewed
+at a glance or organized into different contexts etc.
+Such a pinwall could serve for example to organise references to articles,
+to collect visual inspiration for a moodboard etc.
+
+As a collection, the Pinwall is primarily mapped to a Fileder in the system.
+Any content that is placed within can then be rendered by the Pinwall,
+which can constrain every piece of content to a rectangular piece on its canvas.
+This is possible through a simple script, e.g. of the type `text/moonscript -> fn -> mmm/dom`,
+which enumerates the list of children, wraps each in such a rectangular container,
+and outputs the list of containers as DOM elements.
+
+The position and size of each panel are stored in an ad-hoc facet, encoded in the JSON data format:
+`pinwall_info: text/json`. Such a facet is set on each child and read whenever the script is called
+to render the children, plugging the values within the facet into the visual styling of the document.
+
+The script can also set event handlers that react to user input while the document is loaded,
+and allow the user to reposition and resize the individual pinwall items by clicking and dragging
+on the upper border or lower right-hand corner respectively.
+Whenever a change is made the event handler can then update the value in the `pinwall_info` facet,
+so that the updated position and size are stored for the next time the pinwall is opened.
+
+## 5.3 slideshow
+Another common use of digital documents is as aids in a verbal presentation.
+These often take the form of slideshows, for the creation of which a number of established applications exist.
+In simple terms, a slideshow is simply a linear series of screen-sized documents, that can be
+advanced (and rewound) one by one using keypresses.
+
+The implementation of this is rather straightforward as well.
+The slideshow as a whole becomes a fileder with a script that generates a designated viewport rectangle,
+as well as a control interface with keys for advancing the active slide.
+It also allows putting the browser into fullscreen mode to maximise screenspace and remove  visual elements
+of the website that may distract from the presentation, and register an event handler for keyboard accelerators
+for moving through the presentation.
+
+Finally the script simply embeds the first of its child-fileders into the viewport rectangle.
+Once the current slide is changed, the next embedded child is simply chosen.
+
+<!--
+## code documentation
+/meta/mmm.dom/:%20text/html+interactive
+-->
diff --git a/root/articles/mmmfs/examples/intro: text$markdown+sidenotes.md b/root/articles/mmmfs/examples/intro: text$markdown+sidenotes.md
index 709da5c..7b54d95 100644
--- a/root/articles/mmmfs/examples/intro: text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/examples/intro: text$markdown+sidenotes.md
@@ -1,94 +1,8 @@
-# examples
+# 5. example use-cases
 To illustrate the capabilities of the proposed system, and to compare the results with the framework introduced above,
 a number of example use cases have been chosen and implemented from the perspective of a user.
 In the following section I will introduce these use cases and briefly summarize the implementation
 approach in terms of the capabilities of the proposed system.
 
-## publishing and blogging
-### blogging
-Blogging is pretty straightforward, since it generally just involves publishing lightly-formatted text,
-interspersed with media such as images and videos or perhaps social media posts.
-Markdown is a great tool for this job, and has been integrated in the system to much success:
-There are two different types registered with *converts*: `text/markdown` and `text/markdown+span`.
-They both render to HTML (and DOM nodes), so they are immediately viewable as part of the system.
-The only difference for `text/markdown+span` is that it is limited to a single line,
-and doesn't render as a paragraph but rather just a line of text.
-This makes it suitable for denoting formatted-text titles and other small strings of text. 
-
-The problem of embedding other content together with text comfortably is also solved easily,
-because Markdown allows embedding arbitrary HTML in the document.
-This made it possible to define a set of pseudo-HTML elements in the Markdown-convert,
-`<mmm-embed>` and `<mmm-link>`, which respectively embed and link to other content native to mmm.
-
-### scientific publishing
-<div class="sidenote" style="margin-top: 1.25rem">
-One of the 'standard' solutions, <a href="https://www.latex-project.org/">LaTeX</a>,
-is arguably at least as complex as the mmm system proposed here, but has a much narrower scope,
-since it does not support interaction.
-</div>
-
-Scientific publishing is notoriously complex, involving not only the transclusion of diagrams
-and other media, but generally requiring precise and consistent control over formatting and layout.
-Some of these complexities are tedious to manage, but present good opportunities for programmatic
-systems and media to do work for the writer.
-
-One such topic is the topic of references.
-References appear in various formats at multiple positions in a scientific document;
-usually they are referenced via a reduced visual form within the text of the document,
-and then shown again with full details at the end of the document.
-
-For the sake of this thesis, referencing has been implemented using a subset of the popular
-BibTeX format for describing citations. Converts have been implemented for the `text/bibtex`
-type to convert to a full reference format (to `mmm/dom`) and to an inline side-note reference
-(`mmm/dom+link`) that can be transcluded using the `<mmm-link>` pseudo-tag.
-
-For convenience, a convert from the `URL -> cite/acm` type has been provided to `URL -> text/bibtex`,
-which generates links to the ACM Digital Library<mmm-embed path="../references/acm-dl" wrap="sidenote"></mmm-embed>
-API for accessing BibTeX citations for documents in the library. This means that it is enough to store the link to the
-ACM DL entry in mmmfs, and the reference will automatically be fetched, and therefore stay up to date with potential
-remote corrections.
-
-## pinwall
-In many situations, in particular for creative work, it is often useful to compile resources of
-different types for reference or inspiration, and arrange them spacially so that they can be viewed
-at a glance or organized into different contexts etc.
-Such a pinwall could serve for example to organise references to articles,
-to collect visual inspiration for a moodboard etc.
-
-As a collection, the Pinwall is primarily mapped to a Fileder in the system.
-Any content that is placed within can then be rendered by the Pinwall,
-which can constrain every piece of content to a rectangular piece on its canvas.
-This is possible through a simple script, e.g. of the type `text/moonscript -> fn -> mmm/dom`,
-which enumerates the list of children, wraps each in such a rectangular container,
-and outputs the list of containers as DOM elements.
-
-The position and size of each panel are stored in an ad-hoc facet, encoded in the JSON data format:
-`pinwall_info: text/json`. Such a facet is set on each child and read whenever the script is called
-to render the children, plugging the values within the facet into the visual styling of the document.
-
-The script can also set event handlers that react to user input while the document is loaded,
-and allow the user to reposition and resize the individual pinwall items by clicking and dragging
-on the upper border or lower right-hand corner respectively.
-Whenever a change is made the event handler can then update the value in the `pinwall_info` facet,
-so that the updated position and size are stored for the next time the pinwall is opened.
-
-## slideshow
-Another common use of digital documents is as aids in a verbal presentation.
-These often take the form of slideshows, for the creation of which a number of established applications exist.
-In simple terms, a slideshow is simply a linear series of screen-sized documents, that can be
-advanced (and rewound) one by one using keypresses.
-
-The implementation of this is rather straightforward as well.
-The slideshow as a whole becomes a fileder with a script that generates a designated viewport rectangle,
-as well as a control interface with keys for advancing the active slide.
-It also allows putting the browser into fullscreen mode to maximise screenspace and remove  visual elements
-of the website that may distract from the presentation, and register an event handler for keyboard accelerators
-for moving through the presentation.
-
-Finally the script simply embeds the first of its child-fileders into the viewport rectangle.
-Once the current slide is changed, the next embedded child is simply chosen.
-
-<!--
-## code documentation
-/meta/mmm.dom/:%20text/html+interactive
--->
+<span class="sidenote">The online version is available at [s-ol.nu/ba](https://s-ol.nu/ba).</span>
+The following examples can be viewed and inspected in the interactive version online:
diff --git a/root/articles/mmmfs/examples/text$moonscript -> fn -> mmm$dom.moon b/root/articles/mmmfs/examples/text$moonscript -> fn -> mmm$dom.moon
index 1401e95..6c47270 100644
--- a/root/articles/mmmfs/examples/text$moonscript -> fn -> mmm$dom.moon
+++ b/root/articles/mmmfs/examples/text$moonscript -> fn -> mmm$dom.moon
@@ -31,15 +31,7 @@
 
     li link_to child
 
-  examples = div {
-    style:
-      position: 'relative'
-      'margin-top': '4rem'
+  examples = ul for child in *@children
+    preview child
 
-    div "The online version is available at ", (a "s-ol.nu/ba", href: 'https://s-ol.nu/ba'), ".", class: 'sidenote'
-    "The following examples can be viewed and inspected in the interactive version online:"
-    ul for child in *@children
-      preview child
-  }
-
-  div (@gett 'intro: mmm/dom'), examples
+  div (@gett 'intro: mmm/dom'), examples, (@gett 'implementation: mmm/dom')
diff --git a/root/articles/mmmfs/framework/text$markdown+sidenotes.md b/root/articles/mmmfs/framework/text$markdown+sidenotes.md
index f62c581..81acb02 100644
--- a/root/articles/mmmfs/framework/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/framework/text$markdown+sidenotes.md
@@ -1,12 +1,11 @@
-evaluation framework
-====================
+# 3. evaluation framework
 
 In the following section, I will collect approaches and reviews of different end-user software systems from current
 literature, as well as derive and present my own requirements and guiding principles for the development of a new
 system.
 
-qualities
----------
+3.1 qualities of successful end-user computing
+----------------------------------------------
 
 *Ink and Switch* suggest three qualities for tools striving to support
 end-user programming<mmm-embed path="../references/inkandswitch" wrap="sidenote"></mmm-embed>:
@@ -26,8 +25,8 @@ very abstract. The following properties are therefore derived as more concrete p
 constraints: namely the construction of a system for end-users to keep, structure and display personal information and
 thoughts.
 
-modularity
-----------
+3.2 modularity
+--------------
 
 The *UNIX Philosophy*<mmm-embed path="../references/unix" wrap="sidenote"></mmm-embed> describes the software design
 paradigm pioneered in the creation of the Unix operating system at the AT&T Bell Labs research center in the 1960s. The
@@ -50,8 +49,8 @@ alternate software at any time.
 Settling on a specific modular design model, and reifying other components of a system in terms of it, also corresponds
 directly to the concept of *Embodiment* described by Ink & Switch.
 
-content transclusion
---------------------
+3.3 content transclusion
+------------------------
 
 The strengths of modular architectures should similarily extend also into the way the system will be used by users.
 If users are to store their information and customized behaviour in such an architecture, then powerful tools need to be
@@ -76,8 +75,8 @@ This ability should be integrated deeply into the system, so that data can be tr
 storage conditions, with as little caveats as possible. In particular, the interactions of remote data access and
 content transclusion should be paid attention to and taken into consideration for a system's design.
 
-end-user programming
---------------------
+3.4 end-user programming
+------------------------
 
 In order to provide users full access to their information as well as the computational infrastructure,
 users need to be able to finely customize and reorganize the smallest pieces to suit their own purposes,
diff --git a/root/articles/mmmfs/historical-approaches/text$markdown+sidenotes.md b/root/articles/mmmfs/historical-approaches/text$markdown+sidenotes.md
index 8829f69..812d751 100644
--- a/root/articles/mmmfs/historical-approaches/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/historical-approaches/text$markdown+sidenotes.md
@@ -1,5 +1,4 @@
-historical approaches
-=====================
+# 2. historical approaches
 
 Two of the earliest holistic computing systems, the Xerox Alto and Xerox Star, both developed at Xerox PARC and
 introduced in the 70s and early 80s, pioneered not only graphical user-interfaces, but also the "Desktop Metaphor".
diff --git a/root/articles/mmmfs/mmmfs/$order b/root/articles/mmmfs/mmmfs/$order
index ec11aa6..5a5d5ab 100644
--- a/root/articles/mmmfs/mmmfs/$order
+++ b/root/articles/mmmfs/mmmfs/$order
@@ -1,4 +1,3 @@
-confusion
 type_coercion_graph
 tree_mmmfs
 tree_mainstream
diff --git a/root/articles/mmmfs/mmmfs/confusion/text$markdown.md b/root/articles/mmmfs/mmmfs/confusion/text$markdown.md
deleted file mode 100644
index 55fe833..0000000
--- a/root/articles/mmmfs/mmmfs/confusion/text$markdown.md
+++ /dev/null
@@ -1,5 +0,0 @@
-For example, the difference between changing a file extension and converting a file between two formats is often unclear
-to users, as evident from questions like this: <a
-href="https://askubuntu.com/questions/166602/why-is-it-possible-to-convert-a-file-just-by-renaming-its-extension">
-Why is it possible to convert a file just by renaming it?</a>, https://askubuntu.com/q/166602 from 2019-12-18
-<!-- https://www.quora.com/What-happens-when-you-rename-a-jpg-to-a-png-file -->
diff --git a/root/articles/mmmfs/mmmfs/text$markdown+sidenotes.md b/root/articles/mmmfs/mmmfs/text$markdown+sidenotes.md
index c2bbee5..28030d7 100644
--- a/root/articles/mmmfs/mmmfs/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/mmmfs/text$markdown+sidenotes.md
@@ -1,5 +1,4 @@
-mmmfs
-=====
+# 4. mmmfs
 
 `mmmfs` is a newly developed personal data storage and processing system. It was developed first as a tool for
 generating static websites, but has been extended with live interaction and introspection, as well as embedded
@@ -13,7 +12,7 @@ seemlessly extended and molded to the users needs.
 The abstraction of data types is accomplished using two major components, the *Type System and Coercion Engine* and
 the *Fileder Unified Data Model* for unified data storage and access.
 
-## the fileder unified data model
+## 4.1 the fileder unified data model
 The Fileder Model is the underlying unified data storage model.
 Like many data storage models it is based fundamentally on the concept of a hierarchical tree-structure.
 
@@ -42,16 +41,18 @@ Some notable mechanism are:
 It should be clear already from this short list that to mainstream operating systems, as well as the applications
 running on them, the format of a file is almost completely unknown and at best educated guesses can be made.
 
-<mmm-embed path="confusion" wrap="marginnote" style="margin-top: -3rem;"></mmm-embed>
 Because these various mechanisms are applied at different times by the operating system and applications, it is possible
 for files to be labelled or considered as being in different formats at the same time by different components of the
 system.
 
-This leads to confusion about the factual format of data among users, but can also pose a serious security risk:
+This leads to confusion about the factual format of data among users<mmm-embed path="../references/renaming"
+wrap="sidenote" style="margin-top: -3rem;">For example, the difference between changing a file extension and converting
+a file between two formats is often unclear to users, as evident from questions like this:  </mmm-embed>, but can
+also pose a serious security risk:
 Under some circumstances it is possible that a file contains maliciously-crafted code and is treated as an executable
 by one software component, while a security mechanism meant to detect such code determines the same file to be a
-legitimate image<mmm-embed path="../references/poc-or-gtfo" wrap="sidenote"></mmm-embed> (the file may in fact be valid
-in both formats).
+legitimate image<mmm-embed path="../references/poc-or-gtfo" wrap="sidenote" style="margin-top: 2rem"></mmm-embed>
+(the file may in fact be valid in both formats).
 
 In mmmfs, the example above might look like this instead:
 <mmm-embed path="tree_mmmfs">schematic view of an example mmmfs tree</mmm-embed>
@@ -76,7 +77,7 @@ Semantically a *fileder*, like a *directory*, also encompasses all the other *fi
 (recursively). Since *fileders* are the primary unit of data to be operated upon, *fileder* nesting emerges as a natural
 way of structuring complex data, both for access by the system and its components, as well as the user themself.
 
-## the type system & coercion engine
+## 4.2 the type system & coercion engine
 As mentioned above, *facets* store data alongside its *type*, and when a component of the system requires data from a
 *fileder*, it has to specify the *expected type* (or a list of these) that it requires the data to be in. The system
 then attempts to coerce one of the existing facets into the *expected type*, if possible. This process can involve many
diff --git a/root/articles/mmmfs/motivation/text$markdown+sidenotes.md b/root/articles/mmmfs/motivation/text$markdown+sidenotes.md
index ab18726..9bfdea5 100644
--- a/root/articles/mmmfs/motivation/text$markdown+sidenotes.md
+++ b/root/articles/mmmfs/motivation/text$markdown+sidenotes.md
@@ -1,8 +1,7 @@
-motivation
-==========
+# 1. motivation
 
-application-centric design
---------------------------
+1.1 application-centric design
+------------------------------
 
 The majority of users interact with modern computing systems in the form of smartphones, laptops or desktop PCs,
 using the mainstream operating systems Apple iOS and Mac OS X, Microsoft Windows or Android.
@@ -42,8 +41,8 @@ completely cutting users off from this type of ownership over their technology.
 hide the way desktop operating systems work<mmm-embed path="../references/osx-files" wrap="sidenote"></mmm-embed>,
 mobile systems like Apple's *iOS* already started out as such *walled gardens*.
 
-cloud computing
----------------
+1.2 cloud computing
+-------------------
 
 *Web Apps* often offer similar functionality to other applications, but are subject to additional limitations:
 In most cases, they are only accessible or functional in the presence of a stable internet connection,
@@ -60,8 +59,8 @@ continue servicing a customer, the users data may be irrecoverably lost (or acce
 consequences<mmm-embed path="../references/adobe" wrap="sidenote"></mmm-embed>, especially for professional users, for
 whom an inability to access their tools or their cloud-stored data can pose an existential threat.
 
-inert data (and data formats)
------------------------------
+1.3 inert data (and data formats)
+---------------------------------
 
 Cragg coins the term "inert data"<mmm-embed path="../references/super-powers" wrap="sidenote"></mmm-embed> for the data
 created and left behind by apps and applications in the computing model that is currently prevalent: Most data today
@@ -82,8 +81,8 @@ into the .docx document. If the word-processing application supports this, the o
 otherwise the user may have to remove the old image, insert the new one and carefully ensure that the positioning in
 the document remains intact.
 
-disjointed filesystems
-----------------------
+1.4 disjointed filesystems
+--------------------------
 
 The filesystems and file models used on modern computing devices generally operate on the assumption that every
 individual file stands for itself. Grouping of files in folders is allowed as a convenience for users, but most
diff --git a/root/articles/mmmfs/references/$order b/root/articles/mmmfs/references/$order
index 1e250b7..f50f166 100644
--- a/root/articles/mmmfs/references/$order
+++ b/root/articles/mmmfs/references/$order
@@ -1,20 +1,20 @@
+poc-or-gtfo
+aspect-ratios
+memex
 appliances
-osx-files
-ios-files
 super-powers
-adobe
+dijkstra
+subtext
+mime-types
+alternatives-to-trees
 xerox-star
-memex
-hypercard
-wikipedia
 unix
-subtext
+transclusion
+adobe
+acm-dl
+hypercard
 inkandswitch
 linux-exec
-poc-or-gtfo
-acm-dl
-aspect-ratios
-alternatives-to-trees
-transclusion
-mime-types
-dijkstra
+wikipedia
+osx-files
+renaming
diff --git a/root/articles/mmmfs/references/adobe/text$bibtex b/root/articles/mmmfs/references/adobe/text$bibtex
index 3a83038..fccef37 100644
--- a/root/articles/mmmfs/references/adobe/text$bibtex
+++ b/root/articles/mmmfs/references/adobe/text$bibtex
@@ -2,6 +2,7 @@
   title = {Adobe is cutting off users in Venezuela due to US sanctions},
   url = {https://www.theverge.com/2019/10/7/20904030/adobe-venezuela-photoshop-behance-us-sanctions},
   publisher = {The Verge},
+  author = {Lee, Dami},
   year = {2019},
   visited = {2019-12-18},
 }
diff --git a/root/articles/mmmfs/references/ios-files/text$bibtex b/root/articles/mmmfs/references/ios-files/text$bibtex
deleted file mode 100644
index 7ec911c..0000000
--- a/root/articles/mmmfs/references/ios-files/text$bibtex
+++ /dev/null
@@ -1,6 +0,0 @@
-@online{ios:files,
-  title = {Use the Files app on your iPhone, iPad, or iPod touch},
-  url = {https://support.apple.com/en-us/HT206481},
-  publisher = {Apple},
-  visited = {2019-12-27},
-}
diff --git a/root/articles/mmmfs/references/renaming/text$bibtex b/root/articles/mmmfs/references/renaming/text$bibtex
new file mode 100644
index 0000000..a4aa714
--- /dev/null
+++ b/root/articles/mmmfs/references/renaming/text$bibtex
@@ -0,0 +1,6 @@
+@online{renaming,
+  title = {Why is it possible to convert a file just by renaming it?},
+  url = {https://askubuntu.com/q/166602},
+  publisher = {askubuntu.com},
+  visited = {2019-12-18},
+}
diff --git a/root/articles/mmmfs/references/text$moonscript -> fn -> mmm$dom.moon b/root/articles/mmmfs/references/text$moonscript -> fn -> mmm$dom.moon
index 59b5c54..7d0622c 100644
--- a/root/articles/mmmfs/references/text$moonscript -> fn -> mmm$dom.moon
+++ b/root/articles/mmmfs/references/text$moonscript -> fn -> mmm$dom.moon
@@ -5,7 +5,7 @@
   refs = for ref in *@children
     li ref\gett 'mmm/dom'
   div {
-    h1 "references"
+    h1 "references", id: 'references'
     ol with refs
       refs.style = 'line-height': 'normal'
   }
diff --git a/root/articles/mmmfs/statement-of-originality/text$html+frag.html b/root/articles/mmmfs/statement-of-originality/text$html+frag.html
index d5fd76f..d6dcbc0 100644
--- a/root/articles/mmmfs/statement-of-originality/text$html+frag.html
+++ b/root/articles/mmmfs/statement-of-originality/text$html+frag.html
@@ -1,5 +1,5 @@
 <div class="print-only print-ownpage" style="margin: 4cm 0 0;">
-<h1>Statement of Originality</h1>
+<h1 id="statement">statement of originality</h1>
 <p style="margin-top: 5cm">
 This is to certify that the content of this project, documentation and thesis is my own work. It 
 has not been submitted for any other degree or other purposes. I certify that the intellectual 
diff --git a/root/articles/mmmfs/table-of-contents/text$html+frag.html b/root/articles/mmmfs/table-of-contents/text$html+frag.html
new file mode 100644
index 0000000..f349c1e
--- /dev/null
+++ b/root/articles/mmmfs/table-of-contents/text$html+frag.html
@@ -0,0 +1,89 @@
+<!--
+{
+  const fmt = x => `<a href="#${x.id}">${x.innerText}</a>`;
+
+  const parse = e => ({
+    num: +e.tagName.substr(1),
+    fmt: fmt(e),
+  });
+
+  const render = (list) => {
+    let str = '';
+    let num = 0;
+    for (e of list) {
+      while (e.num > num) {
+        str += '<ol style="list-style: none;">'
+        num += 1;
+      }
+
+      while (e.num < num) {
+        str += '</ol>';
+        num -= 1;
+      }
+
+      str += `<li>${e.fmt}</li>`;
+    }
+    return str;
+  };
+
+  render([...$0.querySelectorAll('h1, h2, h3, h4, h5').values()].map(parse));
+}
+-->
+<section class="print-ownpage">
+  <h1 id="table-of-contents">table of contents</h1>
+  <ol style="list-style: none;">
+      <li><a href="#abstract">abstract</a></li>
+      <li><a href="#table-of-contents">table of contents</a></li>
+      <li><a href="#1-motivation">1. motivation</a></li>
+      <ol style="list-style: none;">
+          <li><a href="#11-application-centric-design">1.1 application-centric design</a></li>
+          <li><a href="#12-cloud-computing">1.2 cloud computing</a></li>
+          <li><a href="#13-inert-data-and-data-formats">1.3 inert data (and data formats)</a></li>
+          <li><a href="#14-disjointed-filesystems">1.4 disjointed filesystems</a></li>
+      </ol>
+      <li><a href="#2-historical-approaches">2. historical approaches</a></li>
+      <li><a href="#3-evaluation-framework">3. evaluation framework</a></li>
+      <ol style="list-style: none;">
+          <li><a href="#31-qualities-of-successful-end-user-computing">3.1 qualities of successful end-user computing</a></li>
+          <li><a href="#32-modularity">3.2 modularity</a></li>
+          <li><a href="#33-content-transclusion">3.3 content transclusion</a></li>
+          <li><a href="#34-end-user-programming">3.4 end-user programming</a></li>
+      </ol>
+      <li><a href="#4-mmmfs">4. mmmfs</a></li>
+      <ol style="list-style: none;">
+          <li><a href="#41-the-fileder-unified-data-model">4.1 the fileder unified data model</a></li>
+          <li><a href="#42-the-type-system--coercion-engine">4.2 the type system & coercion engine</a></li>
+      </ol>
+      <li><a href="#5-example-use-cases">5. example use-cases</a></li>
+      <ol style="list-style: none;">
+          <li><a href="#51-publishing-and-blogging">5.1 publishing and blogging</a></li>
+          <ol style="list-style: none;">
+              <li><a href="#511-blogging">5.1.1 blogging</a></li>
+              <li><a href="#512-scientific-publishing">5.1.2 scientific publishing</a></li>
+          </ol>
+          <li><a href="#52-pinwall">5.2 pinwall</a></li>
+          <li><a href="#53-slideshow">5.3 slideshow</a></li>
+      </ol>
+      <li><a href="#6-evaluation">6. evaluation</a></li>
+      <ol style="list-style: none;">
+          <li><a href="#61-examples">6.1 examples</a></li>
+          <ol style="list-style: none;">
+              <li><a href="#611-publishing-and-blogging">6.1.1 publishing and blogging</a></li>
+              <li><a href="#612-pinwall">6.1.2 pinwall</a></li>
+              <li><a href="#613-slideshow">6.1.3 slideshow</a></li>
+          </ol>
+          <li><a href="#62-general-concerns">6.2 general concerns</a></li>
+          <ol style="list-style: none;">
+              <li><a href="#621-global-set-of-converts">6.2.1 global set of converts</a></li>
+              <li><a href="#622-code-outside-of-the-system">6.2.2 code outside of the system</a></li>
+              <li><a href="#623-type-system">6.2.3 type system</a></li>
+              <li><a href="#624-type-coercion">6.2.4 type-coercion</a></li>
+              <li><a href="#625-in-system-editing">6.2.5 in-system editing</a></li>
+          </ol>
+      </ol>
+      <li><a href="#7-conclusion">7. conclusion</a></li>
+      <li><a href="#references">references</a></li>
+      <li><a href="#ba-log">appendix: project log</a></li>
+      <li><a href="#statement">statement of originality</a></li>
+  </ol>
+</section>
diff --git a/root/articles/mmmfs/text$moonscript -> fn -> mmm$dom.moon b/root/articles/mmmfs/text$moonscript -> fn -> mmm$dom.moon
index 89c9a7d..6c5b1d3 100644
--- a/root/articles/mmmfs/text$moonscript -> fn -> mmm$dom.moon
+++ b/root/articles/mmmfs/text$moonscript -> fn -> mmm$dom.moon
@@ -11,7 +11,6 @@
     append = (a) -> table.insert _this, a
 
     append div {
-      class: 'screen-only'
       h1 'Empowered End-User Computing', style: { 'margin-bottom': 0 }
       p {
         style: