From 41a5ec7c4bfb87d7e16a7edb7a7a77cd3dc9180b Mon Sep 17 00:00:00 2001 From: Jonas Smedegaard Date: Thu, 8 May 2025 14:56:50 +0200 Subject: rewrite intro --- _intro.qmd | 90 ++++++++++++++++++++++++++++++-------------------------------- 1 file changed, 44 insertions(+), 46 deletions(-) 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