Improve documentation

CHANGES.md

@@ -1,5 +1,13 @@
 # Changes
 
+## 3.3.0
+
+Documentation:
+
+- Improve the discoverability of the `\markdownInput` macro.
+  (#381, #382, contributed by @solernou)
+- Encourage alternatives to the `hybrid` option in the user manual. (#382)
+
 ## 3.2.1 (2023-11-23)
 
 Fixes:

markdown.dtx

@@ -1517,10 +1517,35 @@ Next, invoke LuaTeX from the terminal:
 luatex document.tex
 ``````
 A PDF document named `document.pdf` should be produced and contain the text
-“Hello *world*!” Invoking pdfTeX should have the same effect:
+“Hello *world*!”
+
+Instead of LuaTeX, you may also use pdfTeX:
 ``` sh
 pdftex --shell-escape document.tex
 ```````
+This should also produce a PDF document named `document.pdf` with the same content.
+
+***
+
+Instead of writing your markdown document between `\markdownBegin` and
+`\markdownEnd`, you can also include markdown documents using the
+`\markdownInput` macro, similarly to how you might use the `\input` TeX
+primitive to include \TeX{} documents.
+
+Using a text editor, create a text document named `hello.md` with the
+following content:
+``` md
+Hello *world*!
+``````
+Create also a text document named `document.tex` with the following content:
+``` tex
+\input markdown
+\markdownInput{hello.md}
+\bye
+```````
+Next, invoke LuaTeX or pdfTeX from the terminal like in the previous example.
+A PDF document named `document.pdf` should be produced and contain the text
+“Hello *world*!”
 
 ### Using \LaTeX{}
 
@@ -1540,10 +1565,39 @@ Next, invoke LuaTeX from the terminal:
 lualatex document.tex
 ``````
 A PDF document named `document.pdf` should be produced and contain the text “Hello
-*world*!” Invoking pdfTeX should have the same effect:
+*world*!”
+
+Instead of LuaTeX, you may also use pdfTeX:
 ``` sh
 pdflatex --shell-escape document.tex
 ``````
+This should also produce a PDF document named `document.pdf` with the same content.
+
+***
+
+Instead of writing your markdown document between `\begin{markdown}` and
+`\end{markdown}`, you can also include markdown documents using the
+`\markdownInput` macro, similarly to how you might use the `\input` TeX
+primitive to include \LaTeX{} documents.
+
+Using a text editor, create a text document named `hello.md` with the
+following content:
+``` md
+Hello *world*!
+``````
+Create also a text document named `document.tex` with the following content:
+``` tex
+\documentclass{article}
+\usepackage{markdown}
+\begin{document}
+\begin{markdown}
+\markdownInput{hello.md}
+\end{markdown}
+\end{document}
+```````
+Next, invoke LuaTeX or pdfTeX from the terminal like in the previous example.
+A PDF document named `document.pdf` should be produced and contain the text
+“Hello *world*!”
 
 ***
 
@@ -1584,6 +1638,29 @@ A PDF document named `document.pdf` should be produced and contain the text “H
 
 ***
 
+Instead of writing your markdown document between `\startmarkdown` and
+`\stopmarkdown`, you can also include markdown documents using the
+`\inputmarkdown` macro, similarly to how you might use the `\input` TeX
+primitive to include \Hologo{ConTeXt} documents.
+
+Using a text editor, create a text document named `hello.md` with the
+following content:
+``` md
+Hello *world*!
+``````
+Create also a text document named `document.tex` with the following content:
+``` tex
+\usemodule[t][markdown]
+\starttext
+\inputmarkdown{hello.md}
+\stoptext
+```````
+Next, invoke LuaTeX from the terminal like in the previous example.
+A PDF document named `document.pdf` should be produced and contain the text
+“Hello *world*!”
+
+***
+
 As the next step, try typesetting the example documents distributed along with
 the Markdown package:
 ``` sh
@@ -1788,16 +1865,16 @@ following content:
 local kpse = require("kpse")
 kpse.set_program_name("luatex")
 local markdown = require("markdown")
-local input, convert_safe, convert_unsafe, paragraph
+local input, convert_nomath, convert_math, paragraph
 
 input = [[$\sqrt{-1}$ *equals* $i$.]]
-convert_safe = markdown.new()
-convert_unsafe = markdown.new({hybrid = true})
+convert_nomath = markdown.new()
+convert_math = markdown.new({texMathDollars = true})
 paragraph = [[\par]]
 
 print(
-  convert_safe(input) .. paragraph ..
-  convert_unsafe(input)
+  convert_nomath(input) .. paragraph ..
+  convert_math(input)
 )
 ```````
 Next, invoke LuaTeX from the terminal:
@@ -1830,16 +1907,16 @@ named `document.tex` with the following content:
 \input lmfonts
 \directlua{
   local markdown = require("markdown")
-  local input, convert_safe, convert_unsafe, paragraph
+  local input, convert_nomath, convert_math, paragraph
 
   input = [[$\string\sqrt{-1}$ *equals* $i$.]]
-  convert_safe = markdown.new()
-  convert_unsafe = markdown.new({hybrid = true})
+  convert_nomath = markdown.new()
+  convert_math = markdown.new({texMathDollars = true})
   paragraph = [[\par]]
 
   tex.sprint(
-    convert_safe(input) .. paragraph ..
-    convert_unsafe(input)
+    convert_nomath(input) .. paragraph ..
+    convert_math(input)
   )
 }
 \bye
@@ -1878,9 +1955,9 @@ following content:
 \begingroup
 \catcode`\%=12
 \catcode`\#=12
-\input safe
+\input nomath
 \par
-\input unsafe
+\input math
 \endgroup
 \bye
 ```````
@@ -1891,8 +1968,8 @@ $\sqrt{-1}$ *equals* $i$.
 ``````
 Next, invoke LuaTeX from the terminal:
 ``` sh
-texlua ⟨CLI pathname⟩ -- example.md safe.tex
-texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
+texlua ⟨CLI pathname⟩ -- example.md nomath.tex
+texlua ⟨CLI pathname⟩ tex_math_dollars=true -- example.md math.tex
 luatex document.tex
 ``````
 where \meta{CLI pathname} corresponds to the location of the Lua CLI script file,
@@ -1912,8 +1989,8 @@ following text:
 
 Invoking pdfTeX should have the same effect:
 ``` sh
-texlua ⟨CLI pathname⟩ -- example.md safe.tex
-texlua ⟨CLI pathname⟩ hybrid=true -- example.md unsafe.tex
+texlua ⟨CLI pathname⟩ -- example.md nomath.tex
+texlua ⟨CLI pathname⟩ tex_math_dollars=true -- example.md math.tex
 pdftex document.tex
 ``````
 
@@ -11074,7 +11151,7 @@ following content:
 $\sqrt{-1}$ *equals* $i$.
 \markdownEnd
 
-\def\markdownOptionHybrid{true}
+\def\markdownOptionTexMathDollars{true}
 \markdownBegin
 $\sqrt{-1}$ *equals* $i$.
 \markdownEnd
@@ -11186,9 +11263,11 @@ pdftex --shell-escape document.tex
 % \bye
 % ```````
 %
-% The \mref{markdownInput} macro accepts a single parameter with the filename
-% of a markdown document and expands to the result of the conversion of the
-% input markdown document to plain \TeX{}.
+% You can use the \mref{markdownInput} macro to include markdown documents,
+% similarly to how you might use the \mref{input} \TeX{} primitive to include
+% \TeX{} documents. The \mref{markdownInput} macro accepts a single parameter
+% with the filename of a markdown document and expands to the result of the
+% conversion of the input markdown document to plain \TeX{}.
 %
 % \end{markdown}
 %  \begin{macrocode}
@@ -15229,7 +15308,7 @@ following content:
   }^^A
   {^^A
     \everyeof={\noexpand}^^A
-    \edef\filename{\@@input"\jobname.fetched" }^^A
+    \edef\filename{\@@@@input"\jobname.fetched" }^^A
     \includegraphics[width=\textwidth]{\filename}^^A
   }^^A
 }
@@ -20021,7 +20100,7 @@ following content:
 $\sqrt{-1}$ *equals* $i$
 \end{markdown}
 
-\begin{markdown}[hybrid]
+\begin{markdown}[texMathDollars]
 $\sqrt{-1}$ *equals* $i$
 \end{markdown}
 
@@ -21118,7 +21197,7 @@ following content:
 $\sqrt{-1}$ *equals* $i$.
 \stopmarkdown
 
-\setupmarkdown[hybrid = yes]
+\setupmarkdown[texmathdollars = yes]
 \startmarkdown
 $\sqrt{-1}$ *equals* $i$.
 \stopmarkdown
@@ -21207,7 +21286,7 @@ following text:
 %### Typesetting Markdown
 % The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro
 % pair for the typesetting of a markdown document fragment, and defines the
-% \mdef{inputmarkdown} command.
+% \mdef{inputmarkdown} macro.
 %
 % \end{markdown}
 %  \begin{macrocode}
@@ -34462,7 +34541,7 @@ end
 % \begin{markdown}
 %
 %### Typesetting Markdown
-% The \mref{inputmarkdown} is defined to accept an optional argument with
+% The \mref{inputmarkdown} macro is defined to accept an optional argument with
 % options recognized by the \Hologo{ConTeXt} interface (see Section
 % <#sec:context-options>).
 %