describe markdown adoption for code docstrings

1 files changed, 34 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].