From 41a5ec7c4bfb87d7e16a7edb7a7a77cd3dc9180b Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Thu, 8 May 2025 14:56:50 +0200
Subject: rewrite intro

---
 _intro.qmd | 90 ++++++++++++++++++++++++++++++--------------------------------
 1 file changed, 44 insertions(+), 46 deletions(-)

(limited to '_intro.qmd')

diff --git a/_intro.qmd b/_intro.qmd
index 8d2f9ef..20ec406 100644
--- a/_intro.qmd
+++ b/_intro.qmd
@@ -1,63 +1,61 @@
 Markdown is a markup language
-that encourages treating structure as integral part of content
-while postponing styling till later.
-This separation of visual concerns from content and structure
-is harnessed by the document converter Pandoc
-and the Pandoc-based document authoring framework Quarto,
-and is suitable for scholarly writing
-where styling may be dictated by a publisher.
-
-Pandoc and Quarto lack support for annotations
-beyond the specific contexts of hypertext navigation and scholarly citation.
-You can annotate a string as a hyperlink with a title,
-or as a citation with a source reference.
-You can add docuent-wide metadata
-as a YAML structure at the top of the text --
-both using well-defined keys for author, supervisor and publication date
-and arbitrarily added keys.
-And you can produce a web page or a PDF document from your text.
-You cannot, however, write an annotation for a string
-contextually related an arbitrary content domain,
-and then in the output document
-have that annotation suppressed yet accessible as metadata.
-
-Example annotations might include
-one set of numbers is in meter and another in nautical miles,
-one citation being supportive and another a rebuttal,
-or that one quote uses "she" as personal pronoun
-and another uses it derogatory.
-Such meta information tied not to the document as a whole
-but to specific strings in the text
-cannot be written as such --
-i.e. structurally part of the writing
-but communicatively meta to the prose content of the text.
+for unobtrusive annotations of text content.
+Processors exist for many dialects of Markdown,
+but none that supports context annotation.
+
+The markup language Markdown,
+originally intended for authoring HTML,
+has been repurposed for more general document authoring.
+The Markdown-based tool Quarto can render scholarly papers
+conforming to prescribed style guides and document formats
+from Markdown text, void of visual styling.
+The author can emphasize,
+annotate a string as a hyperlink or a citation,
+and declare document-wide metadata
+like authorship, ownership and release date.
+
+## Context annotation is unsupported in Markdown
+
+The author cannot, however, annotate a string with an arbitrary context --
+e.g. that one citation uses the metric system
+while another predates it,
+or that a certain personal pronomen is used supportive or derogatory.
+Such information can be expressed as part of prose, e.g. parenthesised,
+but none of the Markdown dialects generally available to Quarto
+provide a way for context annotations to be omitted in output
+or diverted to document metadata.
 
 ## Problem formulation
 
-Quarto supports hypertext and citation annotations,
-and document-wide metadata.
-The aim of this project is to extend
-Pandoc processing and Quarto authoring workflow
-to support writing arbitrary domain-specific annotations
-which are converted to metadata,
-if possible preserving reference to location of the string.
-
-This aim has been framed with the following problem statement:
+The aim of this project is to extend Quarto
+to detect context annotations
+contained in the source Markdown content,
+suppress them from inclusion in the content of output documents
+and optionally add them to the document metadata of output documents.
 
+This aim has been framed with the following problem statement:  
 **How can Pandoc
-be extended to support domain-specific annotations?**
+be extended to support context annotations?**
 
 To aid in achieving that goal,
 the problem statement has been divided into the following subquestions:
 
 * What are the core qualities of Markdown,
-  and how could a Markdown flavor express domain-specific annotations
+  and how could a Markdown dialect express context annotations
   while maintaining those qualities?
 * How do Quarto convert Markdown source to HTML or PDF output,
   and how can this workflow be extended
-  to cover Markdown with domain-specific annotations?
-* Which approach to altering the workflow of Pandoc and Quarto
-  is more likely efficient and long-term sustainable?
+  to handle context annotations?
+* Which approach to altering Quarto is more likely long-term sustainable?
+* How could reliability of a Pandoc plugin for Quarto be evaluated?
+
+## Maintaining usability and interoperability
+
+A notable challenge is aligning with existing practice and systems.
+Markdown is known for its unobtrusive plaintext editing format,
+and an extension to its vocabulary will need to fit that principle.
+Also,  
+FIXME
 
 ## Motivation
 
-- 
cgit v1.2.3

