describe markdown adoption for code docstrings

2 files changed, 138 insertions, 5 deletions

diff --git a/_markdown.qmd b/_markdown.qmd
index c92e910..639cf3a 100644
--- a/_markdown.qmd
+++ b/_markdown.qmd
@@ -1,18 +1,47 @@
-An authoring style that has grown popular,
-especially among some programmers,
-is to write in a format called Markdown,
-and then compile the final document.
+Markdown is a text markup language
+with an emphasis on being easy for humans to read
+[@Gruber2004].
 
 Compared to word processors like Microsoft Word and LibreOffice Writer,
 Markdown authoring stores both content and markup together
 in a human-readable tekst file.
 
+::: {#fig-formality}
+
+```
+informal        /---------formatted text----------\        formal
+<------v-------------v-------------v-----------------------v---->
+ plain text     informal markup   formal markup    binary format
+                (Markdown)        (HTML, XML, etc.)
+```
+
+Markdown is informal, ASCII-based markup
+[@Leonard2016, p. 4]
+
+:::
+
 HTML is itself a plaintext format,
 but is less human-readable.
 Similarly the format LaTeX is also plaintext,
 but its markdown arguably distracts the reading process
 [@Mailund2019chap2, p. 9].
 
+## Alternatives
+
 Other human-readable document source formats exists.
-FIXME Org-mode.
+
+FIXME reStructuredText.  
+FIXME Org-mode.  
 FIXME AsciiDoc.
+
+## Integration
+
+Markdown is in widespread use.
+
+Major source forges use Markdown by default for `README` files
+[@Github2025; @GitLab2025; @Codeberg2024].
+Some major programming languages
+natively support Markdown in embedded docstrings
+[@Microsoft2023; @Oracle2025; @RustTeam2024];
+others offer optional support
+[@Heesch2025; @Sphinx2025; @JSDoc2023].
diff --git a/ref.bib b/ref.bib
index b06ea93..f114491 100644
--- a/ref.bib
+++ b/ref.bib
@@ -42,6 +42,110 @@
   file      = {:Mailund2019book - Introducing Markdown and Pandoc_ Using Markup Language and Document Converter.pdf:PDF},
 }
 
+@Book{Leonard2016mime,
+  author      = {Sean Leonard},
+  date        = {2016-03},
+  title       = {The text/markdown Media Type},
+  doi         = {10.17487/rfc7763},
+  institution = {Internet Engineering Task Force},
+}
+
+@Electronic{Gruber2004,
+  author  = {John Gruber},
+  date    = {2004-12-17},
+  title   = {Markdown},
+  url     = {https://daringfireball.net/projects/markdown/},
+  urldate = {2025-02-18},
+}
+
+@Book{Leonard2016,
+  author      = {Sean Leonard},
+  date        = {2016-03},
+  title       = {Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations},
+  doi         = {10.17487/rfc7764},
+  institution = {Internet Engineering Task Force},
+}
+
+@Electronic{Heesch2025,
+  author   = {Dimitri van Heesch},
+  date     = {2025-01-09},
+  title    = {Doxygen},
+  url      = {https://doxygen.nl/manual/markdown.html},
+  subtitle = {Markdown support},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{Github2025,
+  date         = {2025-02-18},
+  editor       = {{Github, Inc.}},
+  url          = {https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes},
+  organization = {GitHub, Inc.},
+  urldate      = {2025-02-18},
+}
+
+@Electronic{GitLab2025,
+  author       = {{GitLab Inc.}},
+  date         = {2025-02-17},
+  title        = {GitLab Flavored Markdown (GLFM)},
+  url          = {https://docs.gitlab.com/user/markdown/},
+  organization = {GitLab Inc.},
+  urldate      = {2025-02-18},
+}
+
+@Electronic{Codeberg2024,
+  author   = {{Codeberg Docs Contributors}},
+  date     = {2024-11-29},
+  title    = {Your First Repository},
+  url      = {https://docs.codeberg.org/getting-started/first-repository/},
+  subtitle = {Codeberg Documentation},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{Oracle2025,
+  author   = {{Oracle}},
+  date     = {2025-01-25},
+  title    = {JavaDoc Guide},
+  url      = {https://docs.oracle.com/en/java/javase/23/javadoc/using-markdown-documentation-comments.html#GUID-27E3BB65-BF86-4F8A-9C6C-A864682BEA84},
+  subtitle = {Markdown in Documentation Comments},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{RustTeam2024,
+  author   = {{the Rust Team}},
+  date     = {2024-04-04},
+  title    = {The rustdoc book},
+  url      = {https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html},
+  subtitle = {What is rustdoc?},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{Sphinx2025,
+  author   = {{the Sphinx developers}},
+  date     = {2025-01-29},
+  title    = {Sphinx documentation},
+  url      = {https://www.sphinx-doc.org/en/master/usage/markdown.html},
+  subtitle = {Markdown},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{JSDoc2023,
+  author   = {{the contributors to JSDoc}},
+  date     = {2023-10-31},
+  title    = {Use JSDoc},
+  url      = {https://jsdoc.app/plugins-markdown},
+  subtitle = {Using the Markdown plugin},
+  urldate  = {2025-02-18},
+}
+
+@Electronic{Microsoft2023,
+  date     = {2023-07-12},
+  editor   = {Microsoft},
+  title    = {docfx},
+  url      = {https://dotnet.github.io/docfx/docs/basic-concepts.html},
+  subtitle = {Basic Concepts},
+  urldate  = {2025-02-18},
+}
+
 @Comment{jabref-meta: databaseType:biblatex;}
 
 @Comment{jabref-meta: fileDirectory-jonas-bastian:/home/jonas/Projects/RUC/LIB/md;}