From b4545e4fa7a2d241f1d9ebbfe8a7de403e379c14 Mon Sep 17 00:00:00 2001
From: Jonas Smedegaard <dr@jones.dk>
Date: Wed, 26 Mar 2025 07:16:11 +0100
Subject: reduce intro; move/add chunks to background and design; update
 references

---
 _intro.qmd | 99 +++++++++++++++++++++++---------------------------------------
 1 file changed, 36 insertions(+), 63 deletions(-)

(limited to '_intro.qmd')

diff --git a/_intro.qmd b/_intro.qmd
index 5fc5072..582d9db 100644
--- a/_intro.qmd
+++ b/_intro.qmd
@@ -1,62 +1,35 @@
-The process of authoring a conventional text-based content,
-i.e. texts consisting mainly of a contiguous set of paragraphs,
-can in some sense be described
-as a task of materialising thoughts into a linear form expressed in words.
-The story may consist of moves in time (e.g. a flashback)
-or may not move in time at all (e.g. a dictionary entry),
-but the telling of the story - the text itself - is linear.
-
-*TODO: reference some supportive Writing Process Research*
-
-During such reductive transformation of complex thoughts into linear text,
-the authoring may be aided by the ability
-to annotate some of the contexts omitted.
-A train of thought may contain multiple interconnected trajectories,
-where some are left out when reshaping into the written storyline,
-but the contexts they represent may still be helpful
-during the ongoing writing process,
-even if not intended as part of the storyline specifically.
-
-A concrete example common in academic writing is that of citation.
-The source of an included theory or argument or counterpoint
-is not part of the storyline,
-but a reference to it needs to be maintained
-for accurately compiling a reference list later appended to the text.
-For that specific type of author annotation,
-a range of helper tools exist,
-integrated to various degree with various authoring environments.
-Support for author annotations more generically is less common, however.
-
-*TODO: reference later chapter covering known existing tools*
-
-The choice of authoring environment limit choices of functionality.
-Some authors prefer
-a what-you-see-is-what-you-get (WYSIWYG) authoring environment
-where the words when written
-are visually presented as they would appear in the final document,
-e.g. the word processor Microsoft Word or LibreOffice Writer.
-Other authors favor
-a what-you-see-is-what-you-mean (WYSIWYM) authoring environment
-where the words when written
-are visually presented to emphasize their structural function in the text.
-e.g. the word processor RStudio or the document processor LyX.
-Yet others appreciate
-an environment with technical oversight of both structure and layout
-where prose is intermixed with structural and positioning control commands,
-e.g. directly editing of code for the LaTeX typesetting system.
-Each class of authoring system enables a different set of options
-for author annotations.
-
-Whereas the document formats
-for the commonly used tools Microsoft Word and LibreOffice
-are binary,
-the document formats used with RStudio, LyX and LaTeX
-are plaintext,
-which means the data format avoid the use of control characters
-allowing for editing with general-purpose text editors.
-A fundamental benefit of plaintext formatted texts
-is freedom of choice regarding authoring tools
-[@White2022, p. 3].
+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.
+
+When writing with Quarto,
+you can add intuitive and unobtrusive structural markup
+for headers, emphasis, lists and hyperlinks.
+You can annotate a string as a hyperlink with a title,
+or as a citation with a source reference.
+You can add authors, supervisors and publication date
+as a YAML structure at the top of the text.
+And you can produce a web page or a PDF document from your text,
+sensibly styled and laid out according to academic conventions.
+You cannot, however, annotate a string according to content domain.
+
+Quarto supports hypertext and citation annotations,
+but not arbitrary domain-specific annotations.
+You can spell out in prose
+that one set of numbers is in meter and another in nautical miles,
+or that one citation is supportive and another a rebuttal,
+or that Jane refers to "it" derogatory
+whereas Joe uses "it" as preferred personal pronoun.
+You cannot structurally annotate such details
+omitted from contents of the output document
+yet available for visual styling, indexing
+and other automated processing,
+and as intuitive and unobtrusive writing aid.
 
 ## Problem formulation
 
@@ -71,11 +44,11 @@ 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 can the Markdown syntax be extended
+  and how could a Markdown flavor express domain-specific annotations
   while maintaining those qualities?
-* How do Pandoc and Quarto process Markdown input to HTML or PDF output,
-  and how can this workflow be derived
-  to cover a new flavor of Markdown?
+* 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?
 
-- 
cgit v1.2.3

