diff options
Diffstat (limited to '_intro.qmd')
| -rw-r--r-- | _intro.qmd | 95 |
1 files changed, 34 insertions, 61 deletions
@@ -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. +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. -*TODO: reference some supportive Writing Process Research* +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. -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]. +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? |