<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:mosaic="tag:silasjelley.com,2026:mosaic-feed">

<title>Silas Jelley&#39;s Corner of the Web / Proposals</title>
<link rel="self" type="application/atom+xml" href="https://silasjelley.com/feeds/proposals" />
<link href="https://silasjelley.com/" />
<id>https://silasjelley.com/feeds/proposals/</id>
<icon>/icon/48.ico</icon>
<author>
  <name>Silas Jelley</name>
  <email>reply@silasjelley.com</email>
</author>

<updated>2025-09-23T14:45:34+01:00</updated>
<entry>
  <title>SEP 64: Redesign shortcodes</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2025/09/23/144534" />
  <id>tag:silasjelley.com,2020-08-20:ddcfd972-3c36-4bc6-848c-1d3841c3692c</id>
  <published>2025-09-23T14:45:34+01:00</published>
  <updated>2025-09-23T14:45:34+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>PENDING: [ ] Implement @terminal/shell/command [x] Implement @embedand replace aside:: and import:: substitutions/imports with @embed [ ] Make assets support backlinks so that @link can be used for…</summary>
<mosaic:place>Appledore, South West England, United Kingdom</mosaic:place>
<content type="html">
    &lt;aside class=&#34;aside&#34;&gt;&lt;p&gt;PENDING:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;[ ] Implement &lt;code&gt;@terminal/shell/command&lt;/code&gt;&lt;/li&gt;&lt;li&gt;[x] Implement &lt;code&gt;@embed&lt;/code&gt;and replace &lt;code&gt;aside::&lt;/code&gt; and &lt;code&gt;import::&lt;/code&gt; substitutions/imports with &lt;code&gt;@embed&lt;/code&gt;&lt;/li&gt;&lt;li&gt;[ ] Make assets support backlinks so that &lt;code&gt;@link&lt;/code&gt; can be used for assets too, then review all uses of &lt;code&gt;@val(&amp;#34;id.slug&amp;#34;)&lt;/code&gt; and replace with &lt;code&gt;@link&lt;/code&gt; where possible&lt;/li&gt;&lt;li&gt;[x] Finish migrating all instances of old &lt;code&gt;link::&lt;/code&gt; and &lt;code&gt;slug:&lt;/code&gt; syntax (slug is now &lt;code&gt;@val(&amp;#34;\$uid.slug&amp;#34;)&lt;/code&gt;)&lt;/li&gt;&lt;li&gt;[x] Remove last of the legacy substitution code&lt;/li&gt;&lt;li&gt;[ ] Ultimately I would love to get rid of all regex based substitution schemes and instead parse my documents into an AST and then walk the tree, altering nodes directly, but I’m a ways away from that yet.&lt;/li&gt;&lt;/ul&gt;&lt;/aside&gt;&lt;p&gt;I want a better design for the shortcodes I use throughout the site.&lt;/p&gt;&lt;p&gt;The current “design” is captured in the regexes used to extract them:&lt;/p&gt;&lt;div class=&#34;code-block&#34; data-lang=&#34;python&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;span class=&#34;code-lang&#34;&gt;python&lt;/span&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code data-lang=&#34;python&#34;&gt;    REF_LINK_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;!&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\[&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\]&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\]&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;.&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;+&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    REF_SLUG_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\&amp;lt;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;!`&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;slug::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;a-z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;A-Z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;0-9&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;?:&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;\s&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    REF_TITLE_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;title::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;a-z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;A-Z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;0-9&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;?:&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    REF_CITE_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;cite::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;a-z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;A-Z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;0-9&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;?:&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    REF_IMPT_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(
        &lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\{&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;?:&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;aside&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;|&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;import&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;a-z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;A-Z&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;0-9&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;?:&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; &lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
    )

    text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; page.content.&lt;span style=&#34;color: #4b69c6&#34;&gt;get&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plain&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; text:
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;replace_import_references&lt;/span&gt;(text, REF_IMPT_RE, merged_data, key, page)
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;replace_cite_references&lt;/span&gt;(text, REF_CITE_RE, merged_data)
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;replace_title_references&lt;/span&gt;(text, REF_TITLE_RE, merged_data)
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;replace_slug_references&lt;/span&gt;(text, REF_SLUG_RE, merged_data)
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;process_reference_links&lt;/span&gt;(text, REF_LINK_RE, merged_data, key)
        page.content[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plain&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;] &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; text.&lt;span style=&#34;color: #4b69c6&#34;&gt;strip&lt;/span&gt;()&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;For example, &lt;code&gt;::Author](quote::\$UID)&lt;/code&gt; would be replaced with a quote embed of the provided uid. This design was meant to closely follow the semantics of markdown/Djot links. As my document system expands, and I move further away from existing markup syntax, I want a design that generalises better, provides more legibility and extensibility, and has support for parameters.&lt;/p&gt;&lt;p&gt;TLDR: &lt;code&gt;@keyword(option=&amp;#34;value&amp;#34;)&lt;/code&gt; or something similar.&lt;/p&gt;&lt;p&gt;Core Idea: A single sigil, @, initiates a “function” with a clear name and parameters.&lt;/p&gt;&lt;p&gt;Syntax &amp;amp; Examples:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;p&gt;The Function Call: &lt;code&gt;@command(id, ...)&lt;/code&gt; or &lt;code&gt;@command{...}&lt;/code&gt;&lt;/p&gt;&lt;/li&gt;&lt;li&gt;&lt;p&gt;Links: &lt;code&gt;@link(&amp;#34;a1b2c3d4&amp;#34;, fragment: &amp;#34;...&amp;#34;)[]&lt;/code&gt;&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Could use positional params for brevity: &lt;code&gt;@link(&amp;#34;a1b2c3d4&amp;#34;)[]&lt;/code&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;li&gt;&lt;p&gt;Images/Media:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;code&gt;@img(&amp;#34;a1b2c3d4&amp;#34;, alt: &amp;#34;...&amp;#34;)&lt;/code&gt;&lt;/li&gt;&lt;li&gt;&lt;code&gt;@video(&amp;#34;a1b2c3d4&amp;#34;)&lt;/code&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;li&gt;&lt;p&gt;Inline Data: A dedicated command to retrieve values.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;The title is &lt;code&gt;@val(&amp;#34;a1b2c3d4.title&amp;#34;)&lt;/code&gt;.&lt;/li&gt;&lt;li&gt;Find it at &lt;code&gt;@val(&amp;#34;a1b2c3d4.slug&amp;#34;)&lt;/code&gt;.&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;li&gt;&lt;p&gt;Formatted Content &amp;amp; Transclusion: Each has a clear, named command.&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;@cite(&amp;#34;a1b2c3d4&amp;#34;)
@quote(&amp;#34;a1b2c3d4&amp;#34;)
@embed(&amp;#34;a1b2c3d4&amp;#34;)
@ gallery{
  @img(&amp;#34;b2c3d4e5&amp;#34;)
  @img(&amp;#34;f6&amp;#34;)
} (Block-form for wrapping content)&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;&lt;hr/&gt;&lt;ul&gt;&lt;li&gt;&lt;strong&gt;Key/value parameters vs positional arguments?&lt;/strong&gt;.&lt;br/&gt;&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Positional arguments can be more terse, but like short-opts (vs long-opts) they are less legible and they bake in assumptions. A key/value system is more verbose but removes ambiguity and makes changing defaults, and adding or deprecating arguments much safer.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;There should be a syntax for escaping/skipping a shortcode, when I want the actual shortcode to remain in a document.&lt;/li&gt;&lt;/ul&gt;2:45pm on September 23, 2025 from Appledore, South West England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2064%3A%20Redesign%20shortcodes%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 63: Multiple URLs for source records</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2024/11/06/112332" />
  <id>tag:silasjelley.com,2020-08-20:c5a2e4c4-e7c5-4dcb-94b6-2add1517bd5d</id>
  <published>2024-11-06T11:23:32+03:00</published>
  <updated>2024-11-06T11:23:32+03:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Currently a given reference may optionally include a url key, with a single URL as its value. The idea of a single canonical URL for every resource is somewhat limiting. Replacing the current…</summary>
<mosaic:place>Haydarpaşa, Istanbul, Turkey</mosaic:place>
<content type="html">
    &lt;p&gt;Currently a given reference may optionally include a &lt;code&gt;url&lt;/code&gt; key, with a single URL as its value. The idea of a single canonical URL for every resource is somewhat limiting.&lt;/p&gt;&lt;p&gt;Replacing the current key/value &lt;code&gt;url&lt;/code&gt; with an array, &lt;code&gt;urls&lt;/code&gt;, has the potential to make preservation more adaptable and complete. Example, I don’t subscribe to the New York Times, so when something/someone points me to an article there, I use &amp;lt;archive.is&amp;gt; to view it. So that’s two URLs related to that resource.&lt;/p&gt;&lt;p&gt;The most significant implementation question seems to be whether the new &lt;code&gt;urls&lt;/code&gt; key should contain an Array, or a Dict.&lt;/p&gt;&lt;p&gt;A simple array would force meaning into the order of the array, eg. the attribution constructor would have to index from the beginning or the end of the array, taking the first or the last available value. That feels clumsy.&lt;/p&gt;&lt;p&gt;Using a Dict would allow picking URLs on the basis of semantic keys, eg. an &amp;lt;archive.is&amp;gt; URLs could be under &lt;code&gt;archive_is&lt;/code&gt;, a Quote Investigator link could be under &lt;code&gt;quote_in&lt;/code&gt; OR in a nested &lt;code&gt;references&lt;/code&gt; array etc. Would have to explore whether I really want to ‘hardcode’ such sites.&lt;/p&gt;11:23am on November 6, 2024 from Haydarpaşa, Istanbul, Turkey&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2063%3A%20Multiple%20URLs%20for%20source%20records%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 62: Store quoted content within the source table</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2024/10/19/200222" />
  <id>tag:silasjelley.com,2020-08-20:84a3a895-a4bc-459a-a9e1-cb6bbd54fb2e</id>
  <published>2024-10-19T20:02:22+03:00</published>
  <updated>2024-10-19T20:02:22+03:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Currently, when I quote a piece of text, it lives fully contained in it’s own document. If I want to write some commentary about it or note down some related references, I create a second note which…</summary>
<mosaic:place>Haydarpaşa, Istanbul, Turkey</mosaic:place>
<content type="html">
    &lt;p&gt;Currently, when I quote a piece of text, it lives fully contained in it’s own document. If I want to write some commentary about it or note down some related references, I create a second note which transcludes the quote and write in that. This works, and the separation of concerns appeals to me, but it creates just enough friction that I’m much less likely to write any commentary for most things I quote.&lt;/p&gt;&lt;p&gt;I’m proposing that rather than occupying the &lt;code&gt;content[&amp;#34;plain&amp;#34;]&lt;/code&gt; of a document, a quote reference should instead live in the &lt;code&gt;source&lt;/code&gt; table, perhaps as &lt;code&gt;source[&amp;#34;text&amp;#34;]&lt;/code&gt;?&lt;br/&gt;&lt;code&gt;source[&amp;#34;content&amp;#34;][&amp;#34;plain&amp;#34;]&lt;/code&gt; would be the most appropriate, but nested tables in TOML are frustratingly verbose so I’m not sure (maybe I need YAML after all?).&lt;/p&gt;&lt;p&gt;Example TOML for that:&lt;/p&gt;&lt;div class=&#34;code-block&#34; data-lang=&#34;toml&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;span class=&#34;code-lang&#34;&gt;toml&lt;/span&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code data-lang=&#34;toml&#34;&gt;...

[&lt;span style=&#34;color: #4b69c6&#34;&gt;source&lt;/span&gt;]
&lt;span style=&#34;color: #4b69c6&#34;&gt;title&lt;/span&gt; = &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;The Ten Commandments&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
&lt;span style=&#34;color: #4b69c6&#34;&gt;character&lt;/span&gt; = &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;Sephora (Anne Baxter)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
&lt;span style=&#34;color: #4b69c6&#34;&gt;year&lt;/span&gt; = &lt;span style=&#34;color: #b60157&#34;&gt;1956&lt;/span&gt;
&lt;span style=&#34;color: #4b69c6&#34;&gt;timestamp&lt;/span&gt; = &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;02:02:07&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
[&lt;span style=&#34;color: #4b69c6&#34;&gt;source&lt;/span&gt;.&lt;span style=&#34;color: #4b69c6&#34;&gt;content&lt;/span&gt;]
&lt;span style=&#34;color: #4b69c6&#34;&gt;plain&lt;/span&gt; = &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&amp;#34;&amp;#34;&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;Nothing from some, is more than gold from others.&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&amp;#34;&amp;#34;&lt;/span&gt;
...&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;The current &lt;em&gt;special case&lt;/em&gt; handling of multi-line and literal multi-line strings won’t scale to having many per document, so now would be a good time to solve for that.&lt;/p&gt;&lt;aside class=&#34;aside&#34;&gt;&lt;p&gt;It looks like the &lt;a href=&#34;https://pypi.org/project/tomlkit/&#34;&gt;tomlkit&lt;/a&gt; library preserved multi-line strings by default, which would obviate the need for any special handling.&lt;/p&gt;&lt;p&gt;Discovered by outsourcing the hunt to &lt;a href=&#34;https://www.perplexity.ai&#34;&gt;Perplexity&lt;/a&gt;, which returned the following when asked &lt;em&gt;Is there a python TOML library that can read and write TOML multiline strings without converting them to normal strings?&lt;/em&gt; followed by &lt;em&gt;Show me an example output of tomlkit if printing a multiline string to a file&lt;/em&gt;:&lt;/p&gt;&lt;p&gt;Using the tomlkit library, you can easily write a multiline string to a TOML file while preserving its formatting. Below is an example demonstrating how to create a TOML document with a multiline string and then write it to a file.&lt;/p&gt;&lt;div class=&#34;code-block&#34; data-lang=&#34;python&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;span class=&#34;code-lang&#34;&gt;python&lt;/span&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code data-lang=&#34;python&#34;&gt;&lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;python&lt;/span&gt;

    &lt;span style=&#34;color: #d73948&#34;&gt;from&lt;/span&gt; pathlib &lt;span style=&#34;color: #d73948&#34;&gt;import&lt;/span&gt; Path
    &lt;span style=&#34;color: #d73948&#34;&gt;import&lt;/span&gt; tomlkit

    &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Create a new TOML document&lt;/span&gt;
    doc &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; tomlkit.&lt;span style=&#34;color: #4b69c6&#34;&gt;document&lt;/span&gt;()

    &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Add a comment and a title&lt;/span&gt;
    doc.&lt;span style=&#34;color: #4b69c6&#34;&gt;add&lt;/span&gt;(tomlkit.&lt;span style=&#34;color: #4b69c6&#34;&gt;comment&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;This is a TOML document.&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;))
    doc.&lt;span style=&#34;color: #4b69c6&#34;&gt;add&lt;/span&gt;(tomlkit.&lt;span style=&#34;color: #4b69c6&#34;&gt;nl&lt;/span&gt;())  &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Adds a newline for better formatting&lt;/span&gt;
    doc.&lt;span style=&#34;color: #4b69c6&#34;&gt;add&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;title&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;, &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;TOML Example&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)

    &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Add a multiline string&lt;/span&gt;
    multiline_string &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; tomlkit.&lt;span style=&#34;color: #4b69c6&#34;&gt;multi_line_string&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&amp;#34;&amp;#34;&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;    &lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;Hello,&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;    World!&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;    This is a multiline string.&lt;/span&gt;
&lt;span style=&#34;color: #198810&#34;&gt;    &lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&amp;#34;&amp;#34;&lt;/span&gt;)
    doc.&lt;span style=&#34;color: #4b69c6&#34;&gt;add&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;greeting&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;, multiline_string)

    &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Specify the path to the output file&lt;/span&gt;
    output_file_path &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;Path&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;output.toml&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)

    &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Write the TOML document to a file&lt;/span&gt;
    &lt;span style=&#34;color: #d73948&#34;&gt;with&lt;/span&gt; output_file_path.&lt;span style=&#34;color: #4b69c6&#34;&gt;open&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;w&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;) &lt;span style=&#34;color: #d73948&#34;&gt;as&lt;/span&gt; fout:
        fout.&lt;span style=&#34;color: #4b69c6&#34;&gt;write&lt;/span&gt;(tomlkit.&lt;span style=&#34;color: #4b69c6&#34;&gt;dumps&lt;/span&gt;(doc))

    &lt;span style=&#34;color: #4b69c6&#34;&gt;print&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;TOML document written to &lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;output_file_path&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/aside&gt;&lt;p&gt;If adopted, this would allow for more streamlined ‘quote blogging’, similar to Simon Willison (see &lt;a href=&#34;https://simonwillison.net/2024/Oct/10/bridging-language-gaps-in-multilingual-embeddings-via-contrastiv/&#34;&gt;example&lt;/a&gt;). I will have to give some thought to how I want to present the quotes page though, now that there is more than just quotes involved.&lt;/p&gt;8:02pm on October 19, 2024 from Haydarpaşa, Istanbul, Turkey&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2062%3A%20Store%20quoted%20content%20within%20the%20source%20table%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 61: Designing a metadata vocabulary</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2024/09/28/170529" />
  <id>tag:silasjelley.com,2020-08-20:6d93434e-4da5-465a-901e-8a479d29313e</id>
  <published>2024-09-28T17:05:29+03:00</published>
  <updated>2024-09-28T17:05:29+03:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>This is a meta-proposal, documenting the process of constructing a small metadata vocabulary for the documents and references that make up this hypertext. The goal of this document is to make…</summary>
<mosaic:place>Plovdiv, Bulgaria</mosaic:place>
<content type="html">
    &lt;aside class=&#34;aside&#34;&gt;&lt;p&gt;This proposal is very much a work in progress. You may not find anything useful in here yet.&lt;/p&gt;&lt;/aside&gt;&lt;aside class=&#34;aside&#34;&gt;&lt;p&gt;This is a meta-proposal, documenting the process of constructing a small metadata vocabulary for the documents and references that make up this hypertext. The goal of this document is to make tractable the aims laid out in &lt;a href=&#34;/2023/07/24/105512&#34; title=&#34;SEP 60: A stricter metadata vocabulary | September 2023&#34; data-preview=&#34;/previews/02f7a831-f272-4da5-956a-44b9f052ca1c.html&#34;&gt;SEP 60: A stricter metadata vocabulary&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;I’ll be drawing heavily on the &lt;a href=&#34;https://www.loc.gov/standards/mods/&#34;&gt;US Library of Congress MODS&lt;/a&gt; system and, to a lesser degree, the &lt;a href=&#34;https://www.loc.gov/standards/mads/&#34;&gt;MADS&lt;/a&gt; system. See the links at the bottom of this page for further reading.&lt;/p&gt;&lt;/aside&gt;&lt;p&gt;My intention in the&lt;/p&gt;&lt;p&gt;A metadata vocabulary.&lt;/p&gt;&lt;p&gt;1686653385.#3261M390671128P163708V65024I9218159.locus,S=11814:2,RS&lt;/p&gt;&lt;p&gt;Among other things this system is an extension of an abiding curiosity of mine, that of &lt;em&gt;linked data&lt;/em&gt; and semantic analysis. “This simple idea…remains largely unrealized”&lt;sup class=&#34;fn-ref&#34;&gt;&lt;a href=&#34;#fn1&#34; id=&#34;fnref1&#34; role=&#34;doc-noteref&#34;&gt;1&lt;/a&gt;&lt;/sup&gt;.&lt;/p&gt;&lt;p&gt;While being rooted in a practical context of use, this system adopts an explorative posture that might be summarised as follows.&lt;/p&gt;&lt;p&gt;Consciously unconcerned with stability. This vocabulary is for me, and I reserve the right to make breaking/incompatible changes. This is in contrast to the hypertext interface of this site, where I place a high prize on stability and consider that interface a &lt;em&gt;human API&lt;/em&gt;. I do envision this volatility as being time limited however, as I mean for this to underpin a collaborative body of work, engaging with the inherently generative quality of &lt;em&gt;the collective&lt;/em&gt;&lt;/p&gt;&lt;blockquote&gt;&lt;p&gt;While tags in collaborative tagging systems serve primarily an indexing purpose, facilitating search and navigation of resources, the use of the same tags by more than one individual can yield a collective classification schema.&lt;/p&gt;&lt;cite&gt;— &lt;a href=&#34;/2024/09/28/233246&#34; title=&#34;Lucia Specia and Enrico Motta, “Integrating Folksonomies with the Semantic Web”, The Semantic Web: Research and Applications. ESWC 2007. Lecture Notes in Computer Science, Vol. 4519, pp. 624–639, 2007; Springer, Berlin, Heidelberg&#34;&gt;Lucia Specia and Enrico Motta, “Integrating Folksonomies with the Semantic Web”, &lt;em&gt;The Semantic Web: Research and Applications. ESWC 2007. Lecture Notes in Computer Science, Vol. 4519&lt;/em&gt;, pp. 624–639, 2007&lt;/a&gt;&lt;/cite&gt;&lt;/blockquote&gt;&lt;p&gt;Not afraid to retread old ground, nor to repeat other systems mistakes. Coupled with the freedom to make breaking changes, this permits a pattern of rapid and wide ranging iteration.&lt;/p&gt;&lt;h3 id=&#34;types-of-metadata&#34;&gt;Types of metadata&lt;/h3&gt;&lt;p&gt;There are three substantive types of metadata:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Descriptive Metadata: Information that helps identify and locate data (e.g., title, author).&lt;/li&gt;&lt;li&gt;Structural Metadata: Information about the organization of data (e.g., file structure).&lt;/li&gt;&lt;li&gt;Administrative Metadata: Information regarding data management (e.g., rights, access).&lt;/li&gt;&lt;/ul&gt;&lt;img class=&#34;invert-dark&#34; alt=&#34;The logo of the US Library of Congress&#34; src=&#34;/library/images/logos/Library-of-Congress.svg&#34;/&gt;&lt;p&gt;Suggested reading:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&#34;https://www.loc.gov/standards/mods/design-principles-mods-mads.html&#34;&gt;Design Principles for Enhancements to MODS and MADS&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://www.loc.gov/standards/mods/&#34;&gt;Metadata Object Description Schema (MODS)&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://www.loc.gov/standards/mads/&#34;&gt;Metadata Authority Description Schema (MADS)&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;&lt;section role=&#34;doc-endnotes&#34;&gt;&lt;ol&gt;&lt;li id=&#34;fn1&#34;&gt;Nigel Shadbolt, Tim Berners-Lee, and Wendy Hall. 2006. &lt;a href=&#34;/library/documents/papers/2006_Shadbolt_Hall_Berners_Lee_The_Semantic_Web_Revisited.pdf&#34; title=&#34;The Semantic Web is a Web of actionable information — information derived from data through a semantic theory for interpreting the symbols. This simple idea, however, remains largely unrealized.&#34;&gt;&lt;em&gt;The Semantic Web Revisited&lt;/em&gt;&lt;/a&gt;. IEEE Intelligent Systems Vol. 21, No. 3 (May 2006), 96–101. &lt;a href=&#34;https://doi.org/10.1109/MIS.2006.62&#34;&gt;doi:10.1109/MIS.2006.62&lt;/a&gt;&lt;/li&gt;&lt;/ol&gt;&lt;/section&gt;5:05pm on September 28, 2024 from Plovdiv, Bulgaria&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2061%3A%20Designing%20a%20metadata%20vocabulary%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 60: A stricter metadata vocabulary</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/07/24/105512" />
  <id>tag:silasjelley.com,2020-08-20:02f7a831-f272-4da5-956a-44b9f052ca1c</id>
  <published>2023-09-20T11:31:48+02:00</published>
  <updated>2023-09-20T11:31:48+02:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>This proposal aims to introduce yet more rigour and consistency into the ‘vocabulary’ of metadata terms that I use both in the building of this site but also more broadly. In that sense it is not…</summary>
<mosaic:place>Godet, Switzerland</mosaic:place>
<content type="html">
    &lt;aside class=&#34;aside&#34;&gt;&lt;p&gt;This proposal aims to introduce yet more rigour and consistency into the ‘vocabulary’ of metadata terms that I use both in the building of this site but also more broadly. In that sense it is not strictly a Site Enhancement Proposal, as it effects all of &lt;em&gt;my work&lt;/em&gt; and my digital life.&lt;/p&gt;&lt;/aside&gt;&lt;h3 id=&#34;missing-terms&#34;&gt;Missing terms&lt;/h3&gt;&lt;p&gt;As it stands, the only metadata element I am still scratching around for is one that provides an ‘exclusive group’. This had been the purpose of the &lt;code&gt;type&lt;/code&gt; element (now retired) but I found the term too vague/loaded.&lt;/p&gt;&lt;p&gt;By ‘exclusive’, I mean a categorical element that can only have a single value. A resource can have multiple &lt;code&gt;tags&lt;/code&gt;/&lt;code&gt;subjects&lt;/code&gt; and can belong to multiple &lt;code&gt;collections&lt;/code&gt; but I like the idea of being able to represent that a resource belongs strongly and exclusively to a given branch/realm, whatever.&lt;/p&gt;&lt;p&gt;&lt;em&gt;I’m also open to discarding this notion. Part of what draws me to hypermedia is precisely the fact that it largely obviates the need for exclusive categorisation, so is such a term actually necessary?&lt;/em&gt;&lt;/p&gt;&lt;p&gt;I have found nothing that quite fits in the &lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/&#34;&gt;Dublin Core&lt;/a&gt; which, again, perhaps indicates that it is not a worthwhile pursuit. Still, for now I will continue to explore. Brainstorming has so far yielded:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;notebook&lt;/li&gt;&lt;li&gt;category&lt;/li&gt;&lt;li&gt;space&lt;/li&gt;&lt;li&gt;&lt;s&gt;type&lt;/s&gt;&lt;/li&gt;&lt;li&gt;branch&lt;/li&gt;&lt;li&gt;realm&lt;/li&gt;&lt;li&gt;journal&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Of those, I most like &lt;code&gt;space&lt;/code&gt; and &lt;code&gt;category&lt;/code&gt; as they generalise well. All the terms could work for document-like resources, but I think only those two are general enough to also accommodate other types of resources: images, videos, papers etc.&lt;/p&gt;&lt;p&gt;As it applies to this site, I basically need an element to encode the wandering, nonsense, pearls, etc.&lt;/p&gt;&lt;h3 id=&#34;miscellaneous-notes&#34;&gt;Miscellaneous notes&lt;/h3&gt;&lt;p&gt;&lt;code&gt;type&lt;/code&gt; and &lt;code&gt;class&lt;/code&gt; will be retired.&lt;/p&gt;&lt;p&gt;Add &lt;code&gt;collection&lt;/code&gt; metadata for detecting parent/child etc. A proposal already exists for this, although at that time I had considered using &lt;code&gt;series&lt;/code&gt;.&lt;/p&gt;&lt;p&gt;I don’t intend to create a term for ‘newsletters’ at this time. My reasoning is that this is simply the method of delivery of a resource.&lt;/p&gt;&lt;p&gt;20/09/2023 11:18&lt;/p&gt;&lt;h3 id=&#34;explicit-terms&#34;&gt;Explicit terms&lt;/h3&gt;&lt;dl&gt;&lt;dt&gt;&lt;code&gt;abstract&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/abstract/&#34;&gt;DC:Abstract&lt;/a&gt; A summary of the resource.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;audience&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/audience/&#34;&gt;DC:Audience&lt;/a&gt; For whom the resource is intended or useful.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;available&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/available/&#34;&gt;DC:DateAvailable&lt;/a&gt; Date that the resource became or will become available. Would supersede &lt;code&gt;published&lt;/code&gt;.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;collection&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/dcmitype/Collection/&#34;&gt;DC:Collection&lt;/a&gt; An aggregation of resources.&lt;/p&gt;&lt;p&gt;While I had previously considered introducing the term &lt;code&gt;series&lt;/code&gt;, &lt;code&gt;collection&lt;/code&gt; generalises better as it does not imply a strict sequence. In the near term this may create minor confusion as I already use the word ‘collection’ within the build pipeline, but this vocabulary can be cleared up.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;contributor&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/contributor/&#34;&gt;DC:Contributor&lt;/a&gt; An entity responsible for making contributions to the resource.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;creator&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/creator/&#34;&gt;DC:Creator&lt;/a&gt; An entity responsible for making the resource.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;description&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/description/&#34;&gt;DC:Description&lt;/a&gt; An account of the resource.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;format&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/format/&#34;&gt;DC:Format&lt;/a&gt; The file format, physical medium, or dimensions of the resource.&lt;/p&gt;&lt;p&gt;If adopted, would supersede my &lt;code&gt;type&lt;/code&gt; element. Should perhaps be coupled with &lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/medium/&#34;&gt;DC:Format:Medium&lt;/a&gt; “The material or physical carrier of the resource” where appropriate.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;identifier&lt;/code&gt;&lt;br/&gt;&lt;code&gt;uid&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/identifier/&#34;&gt;DC:Identifier&lt;/a&gt;An unambiguous reference to the resource within a given context.&lt;/p&gt;&lt;p&gt;Currently corresponds with my &lt;code&gt;uid&lt;/code&gt; element.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;language&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/language/&#34;&gt;DC:Language&lt;/a&gt; A language of the resource.&lt;/p&gt;&lt;p&gt;I should decide if I would like for this element to be implicitly assumed to be English where it is not specified, or if I would prefer that it be explicit. Language detection via heuristics at compile time will not be considered.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;license&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/license/&#34;&gt;DC:License&lt;/a&gt; A legal document giving official permission to do something with the resource.&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;location&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/Location/&#34;&gt;DC:Location&lt;/a&gt; A spatial region or named place.&lt;/p&gt;&lt;p&gt;Would usually exist in relation to another term in the vocabulary, eg created &amp;gt; location, available &amp;gt; location, and can possess the following sub-properties:&lt;/p&gt;&lt;p&gt;: &lt;code&gt;lat&lt;/code&gt;&lt;/p&gt;&lt;p&gt;The coordinate of the location measured in the lateral direction.&lt;/p&gt;&lt;p&gt;: &lt;code&gt;long&lt;/code&gt;&lt;/p&gt;&lt;p&gt;The coordinate of the location measured in the longinal direction.&lt;/p&gt;&lt;p&gt;: &lt;code&gt;elevation&lt;/code&gt;&lt;/p&gt;&lt;p&gt;The vertical elevation above mean sea level (&lt;a href=&#34;https://en.wikipedia.org/wiki/Height_above_mean_sea_level&#34;&gt;AMSL&lt;/a&gt;) expressed in metres.&lt;/p&gt;&lt;p&gt;See also &lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-point/&#34;&gt;DCMI Point Encoding Scheme&lt;/a&gt; for further inspiration.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;modified&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/modified/&#34;&gt;DC:Modified&lt;/a&gt; Date on which the resource was changed.&lt;/p&gt;&lt;p&gt;Decide whether this should:&lt;/p&gt;&lt;p&gt;a) not be adopted b) supersede &lt;code&gt;updated&lt;/code&gt; c) compliment &lt;code&gt;updated&lt;/code&gt;&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;publisher&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/publisher/&#34;&gt;DC:Publisher&lt;/a&gt; An entity responsible for making the resource available.&lt;/p&gt;&lt;p&gt;This would be used when referencing, for example: a book.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;subject&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/subject/&#34;&gt;DC:Subject&lt;/a&gt; A topic of the resource.&lt;/p&gt;&lt;p&gt;Would supersede &lt;code&gt;tags&lt;/code&gt;.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;title&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/title/&#34;&gt;DC:Title&lt;/a&gt; A name given to the resource.&lt;/dd&gt;&lt;/dl&gt;&lt;h3 id=&#34;derived-terms&#34;&gt;Derived terms&lt;/h3&gt;&lt;p&gt;Derived terms are those which are not specified in the documents themselves, but rather are populated during the build.&lt;/p&gt;&lt;dl&gt;&lt;dt&gt;&lt;code&gt;backlinks&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/isReferencedBy/&#34;&gt;DC:isReferencedBy&lt;/a&gt; A related resource that references, cites, or otherwise points to the described resource.&lt;/p&gt;&lt;p&gt;I should decide if this should come to include external backlinks or if, as with the seperation of &lt;code&gt;references&lt;/code&gt; and &lt;code&gt;interlinks&lt;/code&gt;, a corresponding element for external inbound links should be created. Such an element could perhaps be called &lt;code&gt;mentions&lt;/code&gt;.&lt;/p&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;interlinks&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;Here the build inserts a list of internal documents that this document references.&lt;/p&gt;&lt;p&gt;Alternatively, could be rolled into the references hierarchy. For example:&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;references:
    external:
        in:
        out:
    internal:
        in:
        out:&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/dd&gt;&lt;dt&gt;&lt;code&gt;references&lt;/code&gt;&lt;/dt&gt;&lt;dd&gt;&lt;p&gt;&lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/terms/references/&#34;&gt;DC:References&lt;/a&gt; A related resource that is referenced, cited, or otherwise pointed to by the described resource.&lt;/p&gt;&lt;p&gt;Despite appearances, this does not correspond with my &lt;code&gt;interlinks&lt;/code&gt; element. At least for now I intend to reserve &lt;code&gt;interlinks&lt;/code&gt; for references between my own documents, as &lt;code&gt;references&lt;/code&gt; may be used for external references.&lt;/p&gt;&lt;/dd&gt;&lt;/dl&gt;11:31am on September 20, 2023 from Godet, Switzerland&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2060%3A%20A%20stricter%20metadata%20vocabulary%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 59: Manifest test</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/06/05/232125" />
  <id>tag:silasjelley.com,2020-08-20:2eda5c1d-3fc7-4a6f-a9cb-ca5ddc0edc68</id>
  <published>2023-06-05T23:21:25+01:00</published>
  <updated>2023-06-05T23:21:25+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>As more and more (eventually all) of the assets that make up this site are specified through JSON manifests, these become a natural entry point for a test harness. Check the ‘source’ field points to…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;As more and more (eventually all) of the assets that make up this site are specified through JSON manifests, these become a natural entry point for a test harness.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Check the ‘source’ field points to a valid resource. This could later be enhanced by confirming that the resource and the a checksum correspond.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;TODO Write a proposal for adding checksums to manifest entries.&lt;/p&gt;11:21pm on June 5, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2059%3A%20Manifest%20test%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 58: Define asset transformations within manifest</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/05/10/123220" />
  <id>tag:silasjelley.com,2020-08-20:523288cc-0f7e-4011-a4d8-894408f25465</id>
  <published>2023-05-10T12:32:20+01:00</published>
  <updated>2023-05-10T12:32:20+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Currently all images are compressed to a fixed ‘quality’ level, this works fine but in some cases (particularly if I’m including an image that has already been compressed/optimised) this results in…</summary>
<mosaic:place>Chaucer, London, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;Currently all images are compressed to a fixed ‘quality’ level, this works fine but in some cases (particularly if I’m including an image that has already been compressed/optimised) this results in double compression with a commensurate and needless drop in quality.&lt;/p&gt;&lt;p&gt;It would be useful to be able dictate how a given asset (eg image/video) is to be transformed during a site build. Initially I would implement for regular images, allowing both a new resolution and a level of compression to be specified in the manifest.&lt;/p&gt;&lt;p&gt;Should there be a default transformation set or should all transformations require explicit specification?&lt;/p&gt;12:32pm on May 10, 2023 from Chaucer, London, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2058%3A%20Define%20asset%20transformations%20within%20manifest%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 57: Reference/include any file from/in documents</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/05/08/002045" />
  <id>tag:silasjelley.com,2020-08-20:6200a919-d546-4b75-9c9a-d7cee440fc8a</id>
  <published>2023-05-08T00:20:45+01:00</published>
  <updated>2023-05-08T00:20:45+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Expand include handling to allow any file to be referenced and included from within any document. This will necessarily have to build on the from the asset manifest. One example would be being able…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;Expand include handling to allow any file to be referenced and included from within any document. This will necessarily have to build on the from the asset manifest.&lt;/p&gt;&lt;p&gt;One example would be being able to embed config files or source code files within documents without having to duplicate content, neatly solving the issue of content drift when one file changes.&lt;/p&gt;12:20am on May 8, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2057%3A%20Reference/include%20any%20file%20from/in%20documents%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 56: Add datetime to metadata fields</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/05/01/123444" />
  <id>tag:silasjelley.com,2020-08-20:8cbd87fe-15e6-4e00-9ce0-dbce2ef83676</id>
  <published>2023-05-01T12:34:44+01:00</published>
  <updated>2023-05-01T12:34:44+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Attach a datetime to (relevant) metadata elements. Example: the proposed ‘confidence’ metadata could track when a document’s confidence status changed from eg ‘middling’ to ‘high’ in this way.</summary>
<mosaic:place>Mangotsfield, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;Attach a datetime to (relevant) metadata elements.&lt;/p&gt;&lt;p&gt;Example: the proposed ‘confidence’ metadata could track when a document’s confidence status changed from eg ‘middling’ to ‘high’ in this way.&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;confidence:
  - &amp;#34;2023-05-01T12:42:45&amp;#34;: &amp;#34;high&amp;#34;
  - &amp;#34;2023-04-12T06:37:01&amp;#34;: &amp;#34;middling&amp;#34;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Alternatively this could all be tracked in a per document changelog, but I think that would brittle, the per document changelog should simply include this information rather than being the arbiter of it.&lt;/p&gt;12:34pm on May 1, 2023 from Mangotsfield, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2056%3A%20Add%20datetime%20to%20metadata%20fields%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 55: Syntax for tasks and spaced repitition cards</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/30/224348" />
  <id>tag:silasjelley.com,2020-08-20:0cdc45c4-377f-41d6-a05f-3fc5692e3b4e</id>
  <published>2023-04-30T22:43:48+01:00</published>
  <updated>2023-04-30T22:43:48+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Djot includes a syntax for marking block content as only being relevant to specific outputs. The below snippet (were it not escaped) would not be visible unless I ran it through a ‘task’ specific…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;&lt;a href=&#34;https://djot.net/&#34;&gt;Djot&lt;/a&gt; includes a syntax for marking block content as only being relevant to specific outputs. The below snippet (were it not escaped) would not be visible unless I ran it through a ‘task’ specific parser. This feature could be used to allow for embedding various blocks within my source documents without them being rendered/exposed in the resulting published HTML.&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;
``` =task
This is a task.
```&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Examples where this could be useful:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Extended comments/todo items within a document that would not be of interest to a reader.&lt;/li&gt;&lt;li&gt;Defining spaced-repetition cards within the context of a relevant document, without that card being passed through to the HTML. This would allow for my viewing said cards either within the context of that document or separated from it for practising.&lt;/li&gt;&lt;li&gt;Same as above but for task management, so that a task could be defined from within any document. This could also support a ‘status’ parameter, perhaps &lt;code&gt;=task:complete&lt;/code&gt;, &lt;code&gt;=task:inprogress&lt;/code&gt;, etc.&lt;/li&gt;&lt;/ul&gt;10:43pm on April 30, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2055%3A%20Syntax%20for%20tasks%20and%20spaced%20repitition%20cards%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 54: Sidenotes</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/30/213309" />
  <id>tag:silasjelley.com,2020-08-20:67cb967a-517d-4c36-b1a8-59f2f527a0e9</id>
  <published>2023-04-30T21:33:09+01:00</published>
  <updated>2023-04-30T21:33:09+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Asides, sidenotes, footnotes, endnotes. Whichever is used, there is often utility in being able to include supplementary information without breaking up the flow or focus of a document. Currently I…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<mosaic:picture>/images/screens/2023/05/01/164339.square.jpg</mosaic:picture>
<content type="html">
    &lt;p&gt;Asides, sidenotes, footnotes, endnotes. Whichever is used, there is often utility in being able to include supplementary information without breaking up the flow or focus of a document.&lt;/p&gt;&lt;p&gt;Currently I use footnotes because HTML supports them natively and reliably. This is an occasional source of frustration in that it forces the reader (usually me) to click/navigate to the footnote and back, breaking context and flow, often resulting in not bothering to check relevant footnotes on the go.&lt;/p&gt;&lt;p&gt;Being able to present footnotes beside their context, without having to force them into the flow of the text itself is perhaps the holy grail for such a feature. Below are a couple examples I’ve come across where this is done well.&lt;/p&gt;&lt;figure class=&#34;gallery two-wide&#34;&gt;&lt;picture&gt;
  &lt;source srcset=&#34;/images/screens/2023/05/01/164339.avif&#34; type=&#34;image/avif&#34;/&gt;
  &lt;img alt=&#34;Prof. G. J. Stein, 2023-05-01&#34; src=&#34;/images/screens/2023/05/01/164339.png&#34; height=&#34;1000&#34; width=&#34;1600&#34;/&gt;&lt;/picture&gt;
&lt;picture&gt;
  &lt;source srcset=&#34;/images/screens/2023/05/01/163754.avif&#34; type=&#34;image/avif&#34;/&gt;
  &lt;img alt=&#34;https://craftinginterpreters.com/scanning.html, 2023-05-01&#34; src=&#34;/images/screens/2023/05/01/163754.png&#34; height=&#34;1000&#34; width=&#34;1600&#34;/&gt;&lt;/picture&gt;
&lt;picture&gt;
  &lt;source srcset=&#34;/images/screens/2023/04/30/150803.avif&#34; type=&#34;image/avif&#34;/&gt;
  &lt;img alt=&#34;A screen of an article by Leo Gao showing an elegant use of sidenotes in web design.&#34; src=&#34;/images/screens/2023/04/30/150803.png&#34; height=&#34;1000&#34; width=&#34;1600&#34;/&gt;&lt;/picture&gt;
&lt;picture&gt;
  &lt;source srcset=&#34;/images/screens/2023/08/22/140157.avif&#34; type=&#34;image/avif&#34;/&gt;
  &lt;img alt=&#34;An article on the JWST at BigThink, 2023-08-22&#34; src=&#34;/images/screens/2023/08/22/140157.png&#34; height=&#34;1000&#34; width=&#34;1600&#34;/&gt;&lt;/picture&gt;

&lt;/figure&gt;
&lt;p&gt;Relevant reading:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&#34;https://gwern.net/sidenote&#34;&gt;Sidenotes In Web Design&lt;/a&gt; — Gwern Branwen&lt;br/&gt;A particularly thorough exploration of the problem space, and the various solutions that have been attempted. Conclusion: none are perfect.&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;Links to examples:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&#34;https://www.chrbutler.com/links/2024-06-05-08-00&#34;&gt;Johannes Klingebiel’s Personal Website – Christopher Butler, 2024-06-12T19:28:07+02:00&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://bmk.sh/2020/08/17/Building-AGI-Using-Language-Models/&#34;&gt;Leo Gao&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://schmud.de/posts/2022-12-05-different-internet.html&#34;&gt;David Schmudde&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://predr.ag/blog/speeding-up-rust-semver-checking-by-over-2000x/&#34;&gt;Predrag’s blog&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://craftinginterpreters.com/scanning.html&#34;&gt;Crafting Interpreters&lt;/a&gt;, &lt;a href=&#34;https://news.ycombinator.com/item?id=35033789&#34;&gt;discovered 2023-04-30&lt;/a&gt;.&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://cs.gmu.edu/~gjstein/2018/12/toward-real-world-alphazero/&#34;&gt;Prof. Gregory J. Stein&lt;/a&gt;, &lt;a href=&#34;https://news.ycombinator.com/item?id=35032991&#34;&gt;discovered 2023-04-30&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#34;https://woahpixels.com/posts/2019/typographic-quest&#34;&gt;Valery Marier, 2024-10-02T10:50:22+03:00&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;9:33pm on April 30, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2054%3A%20Sidenotes%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 53: Metadata switch uid to key</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/30/205803" />
  <id>tag:silasjelley.com,2020-08-20:ebd1a895-b172-4b03-a930-62804889381a</id>
  <published>2023-04-30T20:58:03+01:00</published>
  <updated>2023-04-30T20:58:03+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Currently the unique identifier for a document or other object is stored in its metadata as “uid”. Key seems perhaps more in line with my desire for metadata keys to be clear and descriptive than the…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;Currently the unique identifier for a document or other object is stored in its metadata as “uid”.&lt;/p&gt;&lt;p&gt;Key seems perhaps more in line with my desire for metadata keys to be clear and descriptive than the somewhat outwardly opaque “uid”, it also may fit better grammatically as the iteration toward a more database-like schema continues.&lt;/p&gt;&lt;p&gt;This is a non-essential, non-urgent proposal with no meaningful ramifications, parked here so I can continue to weight it up.&lt;/p&gt;8:58pm on April 30, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2053%3A%20Metadata%20switch%20uid%20to%20key%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 52: Convert all datetime objects to be timezone aware</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/30/204126" />
  <id>tag:silasjelley.com,2020-08-20:c616cdaf-d4b1-4449-bfdb-8011990e96d9</id>
  <published>2023-04-30T20:41:26+01:00</published>
  <updated>2023-04-30T20:41:26+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>My goal for my system of files is for it to be durable through time. To that effect, encoding UTC offsets makes a lot of sense, especially so given that in the last five years I have lived in 6…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;My goal for my system of files is for it to be durable through time. To that effect, encoding UTC offsets makes a lot of sense, especially so given that in the last five years I have lived in 6 different timezones and in the coming few years ahead I will move through many more timezones than that.&lt;/p&gt;&lt;p&gt;Metadata matters.&lt;/p&gt;&lt;p&gt;This proposal has two discrete parts:&lt;/p&gt;&lt;ol&gt;&lt;li value=&#34;1&#34;&gt;Update all existing time datetime objects. This is made easier by my having already encoded &lt;code&gt;location&lt;/code&gt; metadata in all documents.&lt;/li&gt;&lt;li value=&#34;2&#34;&gt;&lt;p&gt;Ensure all new datetime objects going forward have&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Update document creation scripts/flows&lt;/li&gt;&lt;li&gt;Fail to build if any datetime inconsistencies are present.&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;The transformation is subtle but meaningful: &lt;code&gt;2023-04-30 20:52:17&lt;/code&gt; becomes &lt;code&gt;2023-04-30T20:41:26+01:00&lt;/code&gt;.&lt;/p&gt;8:41pm on April 30, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2052%3A%20Convert%20all%20datetime%20objects%20to%20be%20timezone%20aware%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 51: Conflict free editing</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/29/195403" />
  <id>tag:silasjelley.com,2020-08-20:65d33c04-4e69-4844-9cd5-83b249d9d599</id>
  <published>2023-04-29T19:54:03+01:00</published>
  <updated>2023-04-29T19:54:03+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>I store my files on a filesystem, this site is built from that filesystem. This system works for me, but I am interested in research developments in the area of Optimistic Replication, chiefly the…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;I store my files on a filesystem, this site is built from that filesystem. This system works for me, but I am interested in research developments in the area of &lt;em&gt;Optimistic Replication&lt;/em&gt;, chiefly the promise of &lt;a href=&#34;https://crdt.tech/&#34;&gt;Conflict-free Replicated Data Types&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;I’m not interested in a CMS (&lt;a href=&#34;https://en.wikipedia.org/wiki/Content_management_system&#34;&gt;Content management system&lt;/a&gt;) because I spend much of my life ‘offline’, without any internet connectivity. All my workflows are offline-first, with any online component being reached via some method of &lt;a href=&#34;https://en.wikipedia.org/wiki/Eventual_consistency&#34;&gt;eventual consistency&lt;/a&gt;.&lt;/p&gt;&lt;p&gt;Conflict-free Replicated Data Types, or CRDTs, represent an opportunity to modify documents asynchronously while still reaching eventual state consistency, and without merge conflicts. Currently my notes are edited locally (preferred) and replicated between devices using &lt;a href=&#34;https://git-scm.com&#34;&gt;git&lt;/a&gt;. This system of replication is cumbersome when it comes to making modifications from multiple devices. Correcting a typo from my phone has a number of perhaps undesirable pre-requisites:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;A trusted device&lt;/li&gt;&lt;li&gt;A plain text editor&lt;/li&gt;&lt;li&gt;Git&lt;/li&gt;&lt;/ul&gt;&lt;p&gt;The file must be edited, saved, committed to the local git repo, pushed to the remote, and then pulled from that remote by my other devices/clients. If simultaneous edits are made then merge conflicts arise and must be resolved manually.&lt;/p&gt;&lt;p&gt;A preferred workflow, particularly for the making of small corrections or edits to documents, would be to be able to edit the ‘live’ document from anywhere, even if I am offline. CRDTs permit this.&lt;/p&gt;&lt;p&gt;For example, an authenticated instance of a CRDT editor (styled after &lt;a href=&#34;https://github.com/gwgundersen/anno&#34;&gt;Anno&lt;/a&gt; perhaps) could be made available at &lt;code&gt;edit.silasjelley.com&lt;/code&gt;. Changes made there would be replicated via CRDT to my other local working copies of files, whether on my laptop, phone, and the web server that hosts the site. In the latter case, such a change would trigger a rebuild of that page.&lt;/p&gt;&lt;p&gt;&lt;a href=&#34;https://codemirror.net/&#34;&gt;Codemirror&lt;/a&gt; could serve as the editor component of such a flow.&lt;/p&gt;&lt;p&gt;Also of interest in this space is the &lt;a href=&#34;https://docs.datproject.org/docs/intro&#34;&gt;Dat protocol&lt;/a&gt;.&lt;/p&gt;7:54pm on April 29, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2051%3A%20Conflict%20free%20editing%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 50: A personal taxonomical structure</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/29/171715" />
  <id>tag:silasjelley.com,2020-08-20:3bca46c8-9177-4288-8ed4-77d0bc05a1cb</id>
  <published>2023-04-29T17:17:15+01:00</published>
  <updated>2023-04-30T20:05:43+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>A lot of the design of this site has to do with taxonomies, the filing and labelling of the ‘artefacts’ that I produce, be they words, photographs, drawings, audio recordings etc. Taxonomies don’t…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;A lot of the design of this site has to do with taxonomies, the filing and labelling of the ‘artefacts’ that I produce, be they words, photographs, drawings, audio recordings etc.&lt;/p&gt;&lt;p&gt;Taxonomies don’t have to be perfectly stable in order to be useful, and for now the taxonomies I use are in frequent flux as I explore what fits where. That said, as I write more I come to some firmer conclusions about a taxonomical structure that suits the way I think and would like for this structure to become more solid, though not too rigid, with the passing of time.&lt;/p&gt;&lt;p&gt;Sometimes I find myself going in circles, re-treading the same taxonomical ground. Sometimes this bears new fruit but often it is simply the case that I forgot some conclusion that I had already come to and needn’t have spent that time yet again. This document exists as part of an effort to capture the loose taxonomical ideas that occur to me and slowly form them into that more solid structure.&lt;/p&gt;&lt;p&gt;Ideas + time = meaning. Or something like that.&lt;/p&gt;&lt;hr/&gt;&lt;p&gt;The structure of my thinking here is rooted in the paradigm of a simple filesystem, where an object exists in a place and is referenced by it’s location. This paradigm is not sacrosanct to me, but it is a metaphor that has always felt both reasonable and sensible to me. That being said, these taxonomies represent a meta structure and so are not in fact bound by this paradigm, even if that underlying structure were exchanged for a database or an object store this meta-structure would remain.&lt;/p&gt;&lt;p&gt;The semi-stable types/taxons of my writing are explore below in the changing tree below:&lt;/p&gt;&lt;div class=&#34;code-block&#34; data-lang=&#34;console&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;span class=&#34;code-lang&#34;&gt;console&lt;/span&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code data-lang=&#34;console&#34;&gt;Memories
Journal
Nonsense

Notes
    proposals
    quotes
    links&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;I’m also interested in adding a &lt;code&gt;format&lt;/code&gt; element, inspired by standard MIME types (see &lt;a href=&#34;https://datatracker.ietf.org/doc/html/rfc2045&#34;&gt;Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies&lt;/a&gt; and &lt;a href=&#34;https://en.wikipedia.org/wiki/Media_type&#34;&gt;Media type — Wikipedia&lt;/a&gt;).&lt;/p&gt;&lt;p&gt;&lt;code&gt;format&lt;/code&gt; would include a primary and sub-type, for example: text/plain, image/jpeg, audio/music, audio/interview&lt;/p&gt;&lt;p&gt;Other metadata elements could perhaps be derived from the work of &lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/&#34;&gt;Dublin Core&lt;/a&gt;, see &lt;a href=&#34;https://www.dublincore.org/specifications/dublin-core/dcmi-terms/&#34;&gt;DCMI Metadata Terms&lt;/a&gt;.&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;format: The file format, physical medium, or dimensions of the resource.
type: The nature or genre of the resource.
class:
series:
subject:
audience: A class of agents for whom the resource is intended or useful.
tags:
summary: A short description of the document&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;5:17pm on April 29, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2050%3A%20A%20personal%20taxonomical%20structure%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 49: Handler for asset referencing</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/29/143140" />
  <id>tag:silasjelley.com,2020-08-20:90b0bc35-9431-4a6d-ba07-e80e255faf09</id>
  <published>2023-04-29T14:31:40+01:00</published>
  <updated>2023-04-29T14:31:40+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>With SEP 48: Remove assets from notes directory on the road map I still want to preserve the ability to build the site fully locally with asset preview etc. The way forward I see here is in the use…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;With&lt;span style=&#34;white-space: pre-wrap&#34;&gt; &lt;/span&gt;&lt;a href=&#34;/2023/04/23/182806&#34; title=&#34;SEP 48: Remove assets from notes directory | April 2023&#34; data-preview=&#34;/previews/5175aa89-3938-40ca-b5ab-cb3ed93ed2d0.html&#34;&gt;SEP 48: Remove assets from notes directory&lt;/a&gt; on the road map I still want to preserve the ability to build the site fully locally with asset preview etc.&lt;/p&gt;&lt;p&gt;The way forward I see here is in the use of an &lt;em&gt;asset manifest&lt;/em&gt; that tracks all referenced assets. This manifest would be able to specify a local or remote (either or both) source for the asset, give information as to it’s type (eg image/jpeg; document/pdf; text/html), specify creation date, location, title and alt-text, and almost above all, offer a stable UUID for referencing the asset.&lt;/p&gt;&lt;p&gt;JSON seems a sensible format for this manifest. Each object in the manifest would resemble the following:&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&amp;#34;c871b94a-1ef0-47d2-9251-cfd7842c03e8&amp;#34;: {
    &amp;#34;type&amp;#34;: &amp;#34;image&amp;#34;,
    &amp;#34;class&amp;#34;: &amp;#34;photograph&amp;#34;,
    &amp;#34;title&amp;#34;: &amp;#34;Title of the photograph&amp;#34;,
    &amp;#34;alt&amp;#34;: &amp;#34;Optional alt text (title used if not present)&amp;#34;,
    &amp;#34;src&amp;#34;: {
        &amp;#34;old&amp;#34;: &amp;#34;&amp;#34;,
        &amp;#34;local&amp;#34;: &amp;#34;&amp;#34;,
        &amp;#34;remote&amp;#34;:&amp;#34;&amp;#34;
    }
}&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;As with &lt;a href=&#34;/2023/04/18/105742&#34; title=&#34;SEP 45: Transclusion of documents | April 2023&#34; data-preview=&#34;/previews/b9e73360-60b1-4616-83bf-9afab4bce588.html&#34;&gt;transclusion&lt;/a&gt; and &lt;a href=&#34;/2023/04/17/160529&#34; title=&#34;SEP 44: Short Reference Syntax | April 2023&#34; data-preview=&#34;/previews/178c2d67-23ad-4973-a29b-94dacd0b2be0.html&#34;&gt;short referencing&lt;/a&gt; this should be strictly enforced, with a build failing when any non-existent or colliding asset is referenced.&lt;/p&gt;&lt;p&gt;See previous proposals involving handlers: &lt;a href=&#34;/2023/04/18/105742&#34; title=&#34;SEP 45: Transclusion of documents | April 2023&#34; data-preview=&#34;/previews/b9e73360-60b1-4616-83bf-9afab4bce588.html&#34;&gt;SEP 45: Transclusion of documents&lt;/a&gt;, &lt;a href=&#34;/2023/04/17/160529&#34; title=&#34;SEP 44: Short Reference Syntax | April 2023&#34; data-preview=&#34;/previews/178c2d67-23ad-4973-a29b-94dacd0b2be0.html&#34;&gt;SEP 44: Short Reference Syntax&lt;/a&gt;, and &lt;a href=&#34;/2022/08/25/091314&#34; title=&#34;🏗 SEP 8: Create a shorthand for proposals | August 2022&#34; data-preview=&#34;/previews/331fba2f-9730-42a2-9d27-5b0c19a423a0.html&#34;&gt;🏗 SEP 8: Create a shorthand for proposals&lt;/a&gt;.&lt;/p&gt;&lt;h3 id=&#34;the-argument-against-this-proposal&#34;&gt;The argument against this proposal&lt;/h3&gt;&lt;p&gt;It would not be uncharitable to suggest that this proposal would introduce an added layer of indirection between a reference to an asset and the asset itself. Perhaps this comes at the cost of greater conceptual complexity. For now I believe this complexity is both manageable and warranted.&lt;/p&gt;2:31pm on April 29, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2049%3A%20Handler%20for%20asset%20referencing%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 48: Remove assets from notes directory</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/23/182806" />
  <id>tag:silasjelley.com,2020-08-20:5175aa89-3938-40ca-b5ab-cb3ed93ed2d0</id>
  <published>2023-04-23T18:28:06+01:00</published>
  <updated>2023-04-23T18:28:06+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Currently all the sites assets and everything needed to build it live within my ‘notes’ directory. This has advantages in terms of keeping everything needed all together, meaning less has to be…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;Currently all the sites assets and everything needed to build it live within my ‘notes’ directory.&lt;/p&gt;&lt;p&gt;This has advantages in terms of keeping everything needed all together, meaning less has to be mentally kept track of, but as this project grows I find that I want more separation. I don’t like having a subset of my images duplicated between my  /images and  /notes dirs.&lt;/p&gt;&lt;p&gt;For &lt;em&gt;reasons&lt;/em&gt;, I like for my text centric repos to remain small, referencing only those text files. Extraneous assets bloat repos.&lt;/p&gt;&lt;p&gt;I see there being two stages to this proposal:&lt;/p&gt;&lt;ol&gt;&lt;li value=&#34;1&#34;&gt;&lt;p&gt;Migrate image assets out of notes dir (currently at  /notes/assets/images). Most of them are simply duplicated from my  /images directory anyway and I don’t like duplication. Any that for whatever reason are not in my  /images directory will be moved there.&lt;/p&gt;&lt;ul&gt;&lt;li&gt;Create an asset list that allows me to reference images by UUID and also accomodates local and remote refs (for local and production builds of the site).&lt;/li&gt;&lt;/ul&gt;&lt;/li&gt;&lt;li value=&#34;2&#34;&gt;&lt;p&gt;Extract site specific assets and the build script out to a separate repo for development, leaving my  /notes directly purely for… notes!&lt;/p&gt;&lt;/li&gt;&lt;li value=&#34;3&#34;&gt;&lt;p&gt;Begin storing site assets remotely, eg assets.silasjelley.com&lt;br/&gt;Given that I spend much of my time ‘offline’, it will be necessary to also support a local assets store/cache so I can continue to run site builds locally with full asset presence. For this I propose a new handler (see &lt;a href=&#34;/2023/04/29/143140&#34; title=&#34;SEP 49: Handler for asset referencing | April 2023&#34; data-preview=&#34;/previews/90b0bc35-9431-4a6d-ba07-e80e255faf09.html&#34;&gt;SEP 49: Handler for asset referencing&lt;/a&gt;.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;6:28pm on April 23, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2048%3A%20Remove%20assets%20from%20notes%20directory%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 47: Separating moment from memory</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/19/233315" />
  <id>tag:silasjelley.com,2020-08-20:cfbf53a1-fca9-49a9-8565-58ebc180aa0f</id>
  <published>2023-04-19T23:33:15+01:00</published>
  <updated>2023-04-19T23:33:15+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>This is a weird one, but I want a way to reflect both when something was written and when it occurred. For example, I have a memory: Hassan and I stole lollies from Mrs C’s supply cupboard at…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;This is a weird one, but I want a way to reflect both when something was written &lt;em&gt;and&lt;/em&gt; when it occurred. For example, I have a memory:&lt;/p&gt;&lt;p&gt;&lt;em&gt;Hassan and I stole lollies from Mrs C’s supply cupboard at lunchtime while she was outside. She’d left it open and unlocked that day. She was furious. Sent us to the head. When an aid tried to bring us back to class a couple hours later she shouted at us again, eyes bulging she was still so angry. Refused to have us in class for the rest of the day, that aid had to babysit us with a couple workbooks they didn’t understand. Took me a long time to realise how I, more so than Hassan whom she sort expected it from, had betrayed her trust that day. 17 years later it still haunts me.&lt;/em&gt;&lt;/p&gt;&lt;p&gt;Now I wrote this about three months ago, but the event took place about 17 years ago when I was 9 years old. Of course the creation date should reflect that it was written just recently, that it is not the voice of 9 year old me, but I also want to be able to place it on a timeline of my life.&lt;/p&gt;&lt;p&gt;I suppose I could resolve it in the same way as &lt;a href=&#34;https://en.wikipedia.org/wiki/Unix_time&#34;&gt;Unix time&lt;/a&gt;. Only, my ‘epoch’ would be June 9th 1996, the day I was born, everything counting forwards from there.&lt;/p&gt;&lt;p&gt;Today (2023-04-19) is 9,810 days since my birth, so anything I write &lt;em&gt;about&lt;/em&gt; today should have that ‘epoch’ attached, and if tomorrow I write something else about &lt;em&gt;today&lt;/em&gt; it should have the same epoch attached (not tomorrows). At such short timescales this hardly matters, but doing it for documents that refer to events long since past would have the effect of creating two divergent but complimentary entry-points/overviews of this growing corpus.&lt;/p&gt;&lt;p&gt;So the created, updated, published dates remain as they are, but posts also get this new metadata element: &lt;code&gt;day&lt;/code&gt;.&lt;/p&gt;&lt;p&gt;Some thought should be given to an axis for specificity. Example: for the memory I related above, I can definitely figure out what year it happened in (my final year of primary school), I can probably also narrow it down to a three month window within that, but I definitely can’t narrow it down to any given day. So how should that be reflected? Should I just slap the epoch in the middle of the possible range? Should I do that but also express a confidence interval? Expressed either abstractly as low, medium, high, or as a plus/minus range expressed in days. Or something else?&lt;/p&gt;&lt;p&gt;Say I wanted to record an event that I know happened after my brother turned 2 but before I turned 1, that gives me a six month window (we’re 18 months apart), so I could set the epoch squarely in the middle of that and then express a +/-3 month confidence. This would then have to be reflected in the timeline somehow.&lt;/p&gt;&lt;p&gt;In a way this relates to something I &lt;a href=&#34;/linking-forwards&#34; title=&#34;Linking forwards | April 2023&#34; data-preview=&#34;/previews/363f0da0-bbd4-49d3-a48c-5ff250b3660b.html&#34;&gt;just wrote about linking forwards&lt;/a&gt;, I’m trying to develop a more bidirectional relationship with chronology. In this context it might warrant the creation of a new &lt;a href=&#34;/2022/07/14/093954&#34; title=&#34;SEP 4: Add taxonomical types alongside tags | July 2022&#34; data-preview=&#34;/previews/7297dd58-0a93-43f7-9999-6f572b490676.html&#34;&gt;document type&lt;/a&gt;, perhaps called memories. Or perhaps just a class of the journal type, that seems to make more sense. I’m still not confident I have nailed down the ‘final’ hierarchy of types/classes. May need to delve into some librarianship literature for that.&lt;/p&gt;11:33pm on April 19, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2047%3A%20Separating%20moment%20from%20memory%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 46: Per document changelogs</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/19/175544" />
  <id>tag:silasjelley.com,2020-08-20:d89900e6-924e-4692-a97f-b69b9594c752</id>
  <published>2023-04-19T17:55:44+01:00</published>
  <updated>2023-04-19T17:55:44+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>This site has a changelog. I’m pretty remiss at updating it, and in many ways these proposals have made it redundant in terms of tracking major changes to the site itself. But this proposal isn’t for…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;p&gt;This site has a &lt;a href=&#34;/changelogs&#34; title=&#34;Changelog | March 2022&#34; data-preview=&#34;/previews/718c00c2-896a-4021-ad14-c989cd077f63.html&#34;&gt;changelog&lt;/a&gt;. I’m pretty remiss at updating it, and in many ways these proposals have made it redundant in terms of tracking major changes to the site itself. But &lt;em&gt;this&lt;/em&gt; proposal isn’t for the site wide changelog, here I’ll be exploring whether there might be utility in have per document changelogs. Of course, most documents will, at most, a couple of small typo fixes in their lifetime, but for some documents I could see it being useful to track changes. Examples:&lt;/p&gt;&lt;ol&gt;&lt;li value=&#34;1&#34;&gt;&lt;p&gt;Essays. If I make a factual error in an essay and later realise my mistake and correct, I think it’s an ethical requirement to announce that a change has been made to that effect (eg. a newspaper retraction). I don’t want to gaslight people by simply changing what I wrote without making it clear that the words/facts have been changes.&lt;/p&gt;&lt;/li&gt;&lt;li value=&#34;2&#34;&gt;&lt;p&gt;Beliefs: as my &lt;a href=&#34;/beliefs&#34; title=&#34;What do I believe? | April 2022&#34; data-preview=&#34;/previews/cd9f6f68-318a-4749-8ac3-cb91510f757c.html&#34;&gt;beliefs&lt;/a&gt; evolve/develop/change it seems to make sense to record those changes. Is a ‘changelog’ the right format for that? I’m not sure, but I’ll give it a go.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;&lt;p&gt;I think the log should be written into the frontmatter. If a change that warrants recording — not typo fixes, think thematic changes — is made, it could be reflected like so:&lt;/p&gt;&lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;...
changelog:
  - 2023-04-19 18:08:47: A previous version of this essay dated the St. Markus
    quote to 1623. I have since learned that this date is in doubt so it has
    been removed.
  - 2022-01-30 12:49:14: The following figure, previously included in the
    article, has been removed because it may have been exaggerated.
...&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;This changelog could then be emitted in the footer of the document, before or after the footnotes, either in full or collapsed in a &lt;code&gt;\&amp;lt;details&amp;gt;&lt;/code&gt; element.&lt;/p&gt;&lt;p&gt;Some might ask, “why not use version control?” Well, I do use version control, all of this site is versioned in git and pushed to multiple remotes, but if I’m being honest I don’t enjoy git. I love it, don’t get me wrong, using git has saved my but numerous times, but I don’t love using it. My lack of love for interacting with git makes it a non-starter for me in this role.&lt;/p&gt;5:55pm on April 19, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2046%3A%20Per%20document%20changelogs%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>
<entry>
  <title>SEP 45: Transclusion of documents</title>
  <link rel="alternate" type="text/html" href="https://silasjelley.com/2023/04/18/105742" />
  <id>tag:silasjelley.com,2020-08-20:b9e73360-60b1-4616-83bf-9afab4bce588</id>
  <published>2023-04-18T10:57:42+01:00</published>
  <updated>2023-04-18T10:57:42+01:00</updated>
  <category term="notes" />
  <category term="proposals" />
  <summary>Building out SEP 44: Short Reference Syntax presented an opportunity to develop an idea I’ve had in mind for some time, Transclusion. This proposal has since been implemented to a ‘live beta’…</summary>
<mosaic:place>Frenchay, Bristol, England, United Kingdom</mosaic:place>
<content type="html">
    &lt;div class=&#34;code-block&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;Status: Finished but then removed

Date: 2023-04-18
Commit: dd90cb05d8362d869252587e054df23d8d479daf
Code complete

Date: 2023-04-20
Added silent include handler &amp;#39;sin::&amp;#39; for transcluding without a visible break
in styling, as opposed to the visible transclusion block element transcluded
with &amp;#39;in::&amp;#39;

Date: 2024-09-24T11:31:04+03:00
Removed the &amp;#39;sin::&amp;#39; and &amp;#39;in::&amp;#39; handlers as I never use them and I&amp;#39;m preparing to
overhaul the way I do substitutions and transclusions, so first minimising the
surface area of this feature in the current implementation. May revisit in the
future but for now linking is sufficient, this is a hypertext after all.&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;Building out&lt;span style=&#34;white-space: pre-wrap&#34;&gt; &lt;/span&gt;&lt;a href=&#34;/2023/04/17/160529&#34; title=&#34;SEP 44: Short Reference Syntax | April 2023&#34; data-preview=&#34;/previews/178c2d67-23ad-4973-a29b-94dacd0b2be0.html&#34;&gt;SEP 44: Short Reference Syntax&lt;/a&gt; presented an opportunity to develop an idea I’ve had in mind for some time, Transclusion. This proposal has since been implemented to a ‘live beta’ standard.&lt;/p&gt;&lt;blockquote&gt;&lt;dl&gt;&lt;dt&gt;transclusion&lt;/dt&gt;&lt;dd&gt;In computer science, transclusion is the inclusion of part or all of an electronic document into one or more other documents by reference via hypertext. Transclusion is usually performed when the referencing document is displayed, and is normally automatic and transparent to the end user. The result of transclusion is a single integrated document made of parts assembled dynamically from separate sources, possibly stored on different computers in disparate places.&lt;/dd&gt;&lt;/dl&gt;&lt;cite&gt;— &lt;a href=&#34;/2023/04/18/113543&#34;&gt;Wikipedia, &lt;em&gt;Transclusion&lt;/em&gt;&lt;/a&gt;&lt;/cite&gt;&lt;/blockquote&gt;&lt;p&gt;Transclusion has been implemented as a ‘handler’ which finds links prefixed with &lt;code&gt;in::&lt;/code&gt; and substitutes the full content of the referenced document in its place.&lt;/p&gt;&lt;details&gt;&lt;summary&gt;See the relevant code here&lt;/summary&gt;&lt;div class=&#34;code-block&#34; data-lang=&#34;python&#34;&gt;&lt;div class=&#34;code-header&#34; data-mosaic-chrome=&#34;&#34;&gt;&lt;span class=&#34;code-lang&#34;&gt;python&lt;/span&gt;&lt;button class=&#34;code-copy&#34; aria-label=&#34;Copy code&#34; type=&#34;button&#34;&gt;Copy&lt;/button&gt;&lt;/div&gt;&lt;pre&gt;&lt;code data-lang=&#34;python&#34;&gt;&lt;span style=&#34;color: #d73948&#34;&gt;def&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;insertSubstitutions&lt;/span&gt;():
    &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; verbosity &lt;span style=&#34;color: #d73948&#34;&gt;&amp;gt;&lt;/span&gt; &lt;span style=&#34;color: #b60157&#34;&gt;1&lt;/span&gt;:
        &lt;span style=&#34;color: #4b69c6&#34;&gt;print&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;Performing substitutions&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
    transclusion_count &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #b60157&#34;&gt;0&lt;/span&gt;
    transclusion_list &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; []
    &lt;span style=&#34;color: #d73948&#34;&gt;for&lt;/span&gt; key, page &lt;span style=&#34;color: #d73948&#34;&gt;in&lt;/span&gt; data.&lt;span style=&#34;color: #4b69c6&#34;&gt;items&lt;/span&gt;():
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; page[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plaintext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Replace instances of {{ site.pagecount }} and {{ site.wordcount }}&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; accordingly. This is a bodge&lt;/span&gt;
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; text.&lt;span style=&#34;color: #4b69c6&#34;&gt;replace&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;{{&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; site.pagecount &lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;}}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;, &lt;span style=&#34;color: #4b69c6&#34;&gt;str&lt;/span&gt;(site[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;pagecount&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]))
        text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; text.&lt;span style=&#34;color: #4b69c6&#34;&gt;replace&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;{{&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; site.wordcount &lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;}}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;, &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;:,&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;.&lt;span style=&#34;color: #4b69c6&#34;&gt;format&lt;/span&gt;(site[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;wordcount&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]))
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Replace UUID document references in the source text&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; See &amp;#34;SEP: Address documents by their URN/UUID&amp;#34; for the rationale&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Summary: Documents can be referenced from within other documents using&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   their unique ID (UUIDv4), or an 8 digit prefix of that ID. The&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   below code searches for markdown style links that contain a&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   linktarget beginning with &amp;#39;!&amp;#39;. A lookup is performed to match that&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   UID (or partial) UID with a document from which the slug and the&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   title of that document can be discovered. This information is then&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   used to replace the link with one that now points to the public URL&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   of the document instead of the UID. This substitution is performed&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   on plaintext so that both the plaintext and HTML documents reflect&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt;   the authors intent.&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Find all valid UUID reference links, eg:&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; UUID_REF_RE = re.compile(r&amp;#34;\[([^\]]*)\]\((![^)]+)\)&amp;#34;)&lt;/span&gt;
        UUID_REF_RE &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; re.&lt;span style=&#34;color: #4b69c6&#34;&gt;compile&lt;/span&gt;(&lt;span style=&#34;color: #d73948&#34;&gt;r&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\[&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\]&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\]&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\(&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;.&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;*?&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;(&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;^&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #b60157&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #d73948&#34;&gt;+&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;)
        inref_links &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;list&lt;/span&gt;(UUID_REF_RE.&lt;span style=&#34;color: #4b69c6&#34;&gt;findall&lt;/span&gt;(text))
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Process each match&lt;/span&gt;
        &lt;span style=&#34;color: #d73948&#34;&gt;for&lt;/span&gt; linktext_match, inref_type, inref_match &lt;span style=&#34;color: #d73948&#34;&gt;in&lt;/span&gt; inref_links:
            match &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;linktext_match&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;](&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_type&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_match&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
            &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; inref_type &lt;span style=&#34;color: #d73948&#34;&gt;in&lt;/span&gt; [&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;slug::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;, &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;in::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]:
                inref_uuid &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                &lt;span style=&#34;color: #d73948&#34;&gt;for&lt;/span&gt; k &lt;span style=&#34;color: #d73948&#34;&gt;in&lt;/span&gt; data:
                    &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; k.&lt;span style=&#34;color: #4b69c6&#34;&gt;startswith&lt;/span&gt;(inref_match):
                        inref_uuid &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; k
            &lt;span style=&#34;color: #d73948&#34;&gt;else&lt;/span&gt;:
                &lt;span style=&#34;color: #d73948&#34;&gt;raise&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;Exception&lt;/span&gt;(
                    &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;Unexpected Internal Reference type &amp;#39;&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_type&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#39; in document:&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\n&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;                                &lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;key&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\n&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;    match: &lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;match&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                )

            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; If no matching UUID found for reference, raise Exception&lt;/span&gt;
            &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; inref_uuid &lt;span style=&#34;color: #d73948&#34;&gt;==&lt;/span&gt; &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;:
                &lt;span style=&#34;color: #d73948&#34;&gt;raise&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;Exception&lt;/span&gt;(
                    &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\n&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;Unmatched UUID reference:&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\n&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                    &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;  document: &lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;key&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #1d6c76&#34;&gt;\n&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                    &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;  &lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_match&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt; does not reference an existing document&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                )

            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; If linktext is blank OR begins with a &amp;#39;:&amp;#39; lookup the title of&lt;/span&gt;
            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; the linked document. If linktext is not blank AND does NOT begin&lt;/span&gt;
            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; with a &amp;#39;:&amp;#39; leave it as is.&lt;/span&gt;
            &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; linktext_match.&lt;span style=&#34;color: #4b69c6&#34;&gt;startswith&lt;/span&gt;(&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;) &lt;span style=&#34;color: #d73948&#34;&gt;or&lt;/span&gt; linktext_match &lt;span style=&#34;color: #d73948&#34;&gt;==&lt;/span&gt; &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;:
                linktext &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; data[inref_uuid][&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;title&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            &lt;span style=&#34;color: #d73948&#34;&gt;else&lt;/span&gt;:
                linktext &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; linktext_match
            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Lookup slug of linked document&lt;/span&gt;
            linktarget &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;/&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;data&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_uuid&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#39;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;slug&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#39;&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;]&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
            &lt;span style=&#34;color: #d73948&#34;&gt;if&lt;/span&gt; inref_type &lt;span style=&#34;color: #d73948&#34;&gt;==&lt;/span&gt; &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;slug::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;:
                &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Assemble payload&lt;/span&gt;
                replacement &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;[&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;linktext&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;](&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;linktarget&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;)&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;
                &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Find and replace the original link with the updated one&lt;/span&gt;
                text &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; text.&lt;span style=&#34;color: #4b69c6&#34;&gt;replace&lt;/span&gt;(match, replacement)

            &lt;span style=&#34;color: #d73948&#34;&gt;elif&lt;/span&gt; inref_type &lt;span style=&#34;color: #d73948&#34;&gt;==&lt;/span&gt; &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;in::&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;:
                transclude_data &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; {
                    &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;insrc_uuid&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;: key,
                    &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;insrc_match&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;: match,
                    &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_uuid&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;: inref_uuid,
                    &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_linktext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;: linktext,
                    &lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_linktarget&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;: linktarget,
                }
                transclusion_list.&lt;span style=&#34;color: #4b69c6&#34;&gt;append&lt;/span&gt;(transclude_data)

        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Write modified plaintext back to document variable once all&lt;/span&gt;
        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; substitutions have been carried out.&lt;/span&gt;
        page[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plaintext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;] &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; text

        &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Carry out transclusions (these must occur after all other link references to ensure such links are present in transcludes elements)&lt;/span&gt;
        &lt;span style=&#34;color: #d73948&#34;&gt;for&lt;/span&gt; transclude &lt;span style=&#34;color: #d73948&#34;&gt;in&lt;/span&gt; transclusion_list:
            insrc_uuid &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; transclude[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;insrc_uuid&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            insrc_match &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; transclude[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;insrc_match&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            inref_uuid &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; transclude[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_uuid&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            inref_transclude &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #4b69c6&#34;&gt;markdown&lt;/span&gt;(data[inref_uuid][&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plaintext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;])
            linktext &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; transclude[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_linktext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            linktarget &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; transclude[&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;inref_linktarget&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;]
            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Assemble payload&lt;/span&gt;
            replacement &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; &lt;span style=&#34;color: #d73948&#34;&gt;f&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#39;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;lt;figure class=&amp;#34;transclusion&amp;#34;&amp;gt;&amp;lt;p&amp;gt;&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;inref_transclude&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;lt;/p&amp;gt;&amp;lt;figcaption&amp;gt; &amp;lt;em&amp;gt;from&amp;lt;/em&amp;gt; &amp;lt;a href=&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;linktarget&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&amp;gt;&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;{&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;linktext&lt;/span&gt;&lt;span style=&#34;color: #8b41b1&#34;&gt;}&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;lt;/a&amp;gt;&amp;lt;/figcaption&amp;gt;&amp;lt;/figure&amp;gt;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#39;&lt;/span&gt;
            &lt;span style=&#34;color: #74747c&#34;&gt;#&lt;/span&gt;&lt;span style=&#34;color: #74747c&#34;&gt; Find and replace the original link with the assembled transclusion&lt;/span&gt;
            data[insrc_uuid][&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plaintext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;] &lt;span style=&#34;color: #d73948&#34;&gt;=&lt;/span&gt; data[insrc_uuid][&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;plaintext&lt;/span&gt;&lt;span style=&#34;color: #198810&#34;&gt;&amp;#34;&lt;/span&gt;].&lt;span style=&#34;color: #4b69c6&#34;&gt;replace&lt;/span&gt;(
                insrc_match, replacement
            )&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;/details&gt;&lt;p&gt;Drawbacks and pitfalls:&lt;/p&gt;&lt;ol&gt;&lt;li value=&#34;0&#34;&gt;&lt;p&gt;Transclusions do not create backlinks because they are injected as HTML, not markdown.&lt;/p&gt;&lt;/li&gt;&lt;li value=&#34;0&#34;&gt;&lt;p&gt;All types of substitution currently are unable to ignore text in eg, code blocks. In some ways this could be seen as an advantage in that I can perform substitutions anywhere in the text, but this behaviour will need refining.&lt;/p&gt;&lt;/li&gt;&lt;li value=&#34;0&#34;&gt;&lt;p&gt;In the current implementation, all substitutions (ID referencing + transclusion) must be carried out &lt;em&gt;before&lt;/em&gt; HTML is generated. This means that for transclusions to be rich ie, include proper links and formatting, the transcluded page has to be generated twice: once during transclusion and again when the build reaches the true &lt;code&gt;generateHTML()&lt;/code&gt; function.&lt;/p&gt;&lt;/li&gt;&lt;li value=&#34;0&#34;&gt;&lt;p&gt;Currently only supports transcluding whole documents. The ability to transclude parts of documents would necessitate a dramatic overhaul of the build system and arguably would offer very little value. This site favours atomicity: small documents, heavily interlinked. I don’t envision transclusion being used often, and when it is used, I am likely to only want the full content of a short document simply to prevent a reader needing to exit the document to read eg, a term definition. Transclusion therefore is likely mostly just for such use, so that I don’t have to repeat definitions throughout many documents, which would make it harder to refine that definition later. In this way, I am happy with the current implementation.&lt;/p&gt;&lt;/li&gt;&lt;/ol&gt;10:57am on April 18, 2023 from Frenchay, Bristol, England, United Kingdom&lt;p&gt;&lt;a href=&#34;mailto:reply@silasjelley.com?subject=Reply%20to%3A%20%E2%80%9CSEP%2045%3A%20Transclusion%20of%20documents%E2%80%9D&#34;&gt;Reply via email&lt;/a&gt;&lt;/p&gt;
</content>
</entry>

<div xmlns="http://www.w3.org/1999/xhtml" id="feed-chrome" hidden="" data-stylesheet="/style.css?a959535639bceb541eb7a955189913b9">
<header class="site-header">
<nav class="site-nav" aria-label="Site">
<a class="homelink" href="/" title="Homepage of silasjelley.com">Silas Jelley</a>
<ul class="navmain">
<li><a href="/wandering" title="Tales of my worldly travels">Wandering</a></li>
<li><a href="/rambling" title="The ramblings of an itinerant fool">Rambling</a></li>
<li><a href="/nonsense" title="Shaking my brain stem and seeing what fruit falls">Nonsense</a></li>
<li><a href="/quotes" title="Quotes, saved from anything and anywhere I find interest">Quotes</a></li>
</ul>
<ul class="navmisc top">
<li><a href="/about" title="Learn a little more about the author.">About</a></li>
<li><a href="/contact" title="Get in touch with me!">Contact</a></li>
<li><a href="/search" title="Search silasjelley.com">Search</a></li>
<li class="theme-choice" hidden=""><select class="theme-select" aria-label="Theme" title="Colour theme"><option value="system">Auto</option><option value="sepia">Sepia</option><option value="sepia-dark">Sepia dark</option><option value="light">Light</option><option value="dark">Dark</option></select></li>
</ul>
</nav>
</header>
<footer class="site-footer">
<p class="eyebrow">
<a href="/">Silas Jelley</a>
<a href="/feeds" title="Every feed on the site">Feeds</a>
<a href="/about">About</a>
<a href="/contact">Contact</a>
<a href="#top">Top ↑</a>
</p>
</footer>
</div>
<script xmlns="http://www.w3.org/1999/xhtml" src="/js/theme.js?04109bde1f72"></script>
<script xmlns="http://www.w3.org/1999/xhtml" src="/js/feed.js?aeaf63aa0cfc"></script>
</feed>