From 2d25808a88c624638eaf05b120d9851ad470e0d5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 11:39:36 +0100 Subject: [PATCH 01/16] Use first-class YAML commands in `markdown.dtx` and in the example documents --- examples/context-mkiv.tex | 35 +++++++++++++++++++++++++++++++++++ examples/latex-luatex.tex | 9 +++------ examples/latex-pdftex.tex | 9 +++------ markdown.dtx | 2 ++ 4 files changed, 43 insertions(+), 12 deletions(-) diff --git a/examples/context-mkiv.tex b/examples/context-mkiv.tex index 6cb185802..f038377e0 100644 --- a/examples/context-mkiv.tex +++ b/examples/context-mkiv.tex @@ -57,6 +57,41 @@ \starttext +% Set and typeset the document metadata using a YAML metadata block. +\def\doctitle#1{\gdef\@title{#1}} +\def\author#1{\gdef\@author{#1}} +\def\date#1{\gdef\@date{#1}} + +\setupyaml + [ + jekyllDataRenderers = { + title = {\doctitle{#1}}, + author = {\author{#1}}, + date = {\date{#1}}, + }, + renderers = { + jekyllDataEnd = {% + \startalignment[center] + \blank[force,2*big] + {\tfd \@title} + \blank[3*medium] + {\tfa \@author} + \blank[2*medium] + {\tfa \@date} + \blank[3*medium] + \stopalignment + }, + } + ] + +\startyaml + +title: An Example *Markdown* Document +author: Vít Starý Novotný +date: `\currentdate`{=tex} + +\stopyaml + % Typeset the document `example.md` by letting the Markdown package handle % the conversion internally. Optionally, we can specify additional options % between the square brackets similarly to the command `\setupmarkdown`. diff --git a/examples/latex-luatex.tex b/examples/latex-luatex.tex index 51be09c1f..370ce2f23 100644 --- a/examples/latex-luatex.tex +++ b/examples/latex-luatex.tex @@ -12,7 +12,6 @@ fencedCode, hashEnumerators, inlineNotes, - jekyllData, lineBlocks, notes, pipeTables, @@ -28,13 +27,11 @@ texMathSingleBackslash, ]{markdown} % Set the document metadata using a YAML metadata block. -\begin{markdown}[hybrid] ---- +\begin{yaml} title: An Example *Markdown* Document author: Vít Starý Novotný -date: \today ---- -\end{markdown} +date: `\today`{=tex} +\end{yaml} \begin{document} % Typeset the document `example.md` by letting the Markdown package handle % the conversion internally. diff --git a/examples/latex-pdftex.tex b/examples/latex-pdftex.tex index 34f78707c..b53044354 100644 --- a/examples/latex-pdftex.tex +++ b/examples/latex-pdftex.tex @@ -13,7 +13,6 @@ fencedCode, hashEnumerators, inlineNotes, - jekyllData, lineBlocks, notes, pipeTables, @@ -29,13 +28,11 @@ texMathSingleBackslash, ]{markdown} % Set the document metadata using a YAML metadata block. -\begin{markdown}[hybrid] ---- +\begin{yaml} title: An Example *Markdown* Document author: Vít Starý Novotný -date: \today ---- -\end{markdown} +date: `\today`{=tex} +\end{yaml} \begin{document} % Typeset the document `example.md` by letting the Markdown package handle % the conversion internally. diff --git a/markdown.dtx b/markdown.dtx index 7959a8b2f..2ce347539 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -830,6 +830,8 @@ abbr { }% }, }, +} +\yamlSetup{ jekyllDataRenderers = { /authors/* = {% \expandafter\gdef From a11f19064e0354063eea15be51a4a368d1a121d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 11:53:16 +0100 Subject: [PATCH 02/16] Add commands `\yamlSetup` and `\setupyaml` --- markdown.dtx | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/markdown.dtx b/markdown.dtx index 2ce347539..39536990e 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -12065,6 +12065,18 @@ following code in your plain \TeX{} document: \markdownSetup \@@_setup:n % \end{macrocode} +% \begin{markdown} +% +% The command \mdef{yamlSetup} is also available as an alias for the command +% \mref{markdownSetup}. +% +% \end{markdown} +% \begin{macrocode} +\cs_gset_eq:NN + \yamlSetup + \markdownSetup +% \end{macrocode} +% % \iffalse % %<*manual-options> @@ -22995,6 +23007,17 @@ following text: % \end{macrocode} % \begin{markdown} % +% The command \mdef{setupyaml} is also available as an alias for +% the command \mref{setupmarkdown}. +% +% \end{markdown} +% \begin{macrocode} +\cs_gset_eq:NN + \setupyaml + \setupmarkdown +% \end{macrocode} +% \begin{markdown} +% %#### Generating Plain \TeX{} Option Macros and Key-Values % % Unlike plain \TeX{}, we also accept caseless variants of options From 30457f44bdadcf8f6b94d9bf21ef47513c513790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 12:14:52 +0100 Subject: [PATCH 03/16] Add command `\yamlInput` --- markdown.dtx | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/markdown.dtx b/markdown.dtx index 39536990e..c01c0458a 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11830,7 +11830,8 @@ pdftex --shell-escape document.tex %### Typesetting Markdown {#tex-typesetting} % % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, -% \mdef{markinline}, \mdef{markdownInput}, and \mdef{markdownEscape} macros. +% \mdef{markinline}, \mdef{markdownInput}, \mdef{yamlInput}, and +% \mdef{markdownEscape} macros. % % The \mref{markdownBegin} macro marks the beginning of a markdown document % fragment and the \mref{markdownEnd} macro marks its end. @@ -11945,6 +11946,45 @@ pdftex --shell-escape document.tex % \bye % ``````` % +% You can use the \mref{yamlInput} macro to include \acro{YAML} documents, +% similarly to how you might use the \mref{input} \TeX{} primitive to include +% \TeX{} documents. The \mref{yamlInput} macro accepts a single parameter with +% the filename of a \acro{YAML} document and expands to the result of the +% conversion of the input \acro{YAML} document to plain \TeX{}. +% +% \end{markdown} +% \begin{macrocode} +\def\yamlInput#1{% + \begingroup + \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData}% + \markdownInput{#1}% + \endgroup +}% +% \end{macrocode} +% \par +% \begin{markdown} +% +% This macro is also not subject to the limitations of the +% \mref{markdownBegin} and \mref{markdownEnd} macros. +% +% The following example plain \TeX{} code showcases the usage of the +% \mref{markdownInput} macro: +% +% ``` tex +% \input markdown +% \yamlInput{hello.yml} +% \bye +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \input markdown +% \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData} +% \markdownInput{hello.yml} +% \bye +% ``````` +% % The \mref{markdownEscape} macro accepts a single parameter with the filename % of a \TeX{} document and executes the \TeX{} document in the middle of a % markdown document fragment. Unlike the `\input` built-in of \TeX, From 0fddb1bf184c0d925d4ec59692a24e9352c6d1b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 12:52:36 +0100 Subject: [PATCH 04/16] Add commands `\yamlBegin` and `\yamlEnd` --- markdown.dtx | 73 +++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index c01c0458a..60d524976 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11827,11 +11827,13 @@ pdftex --shell-escape document.tex % \noindent It is expected that the special plain \TeX{} characters have the % expected category codes, when `\input`ting the file. % -%### Typesetting Markdown {#tex-typesetting} +%### Typesetting Markdown and YAML {#tex-typesetting} % % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, -% \mdef{markinline}, \mdef{markdownInput}, \mdef{yamlInput}, and -% \mdef{markdownEscape} macros. +% \mdef{yamlBegin}, \mref{yamlEnd}, \mdef{markinline}, \mdef{markdownInput}, +% \mdef{yamlInput}, and \mdef{markdownEscape} macros. +% +%#### Typesetting Markdown and YAML directly % % The \mref{markdownBegin} macro marks the beginning of a markdown document % fragment and the \mref{markdownEnd} macro marks its end. @@ -11889,6 +11891,44 @@ pdftex --shell-escape document.tex % \bye % ``````` % +% The \mref{yamlBegin} macro marks the beginning of an \acro{YAML} document +% fragment and the \mref{yamlEnd} macro marks its end. +% +% \end{markdown} +% \begin{macrocode} +\let\yamlBegin\relax +\let\yamlEnd\relax +% \end{macrocode} +% \par +% \begin{markdown} +% +% The \mref{yamlBegin} and \mref{yamlEnd} macros are subject to the same +% limitations as the \mref{markdownBegin} and \mref{markdownEnd} macros. +% +% The following example plain \TeX{} code showcases the usage of the +% \mref{markdownBegin} and \mref{markdownEnd} macros: +% +% ``` tex +% \input markdown +% \yamlBegin +% title: _Hello **world** +% author: John Doe +% \yamlEnd +% \bye +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \input markdown +% \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData} +% \markdownBegin +% title: _Hello **world** +% author: John Doe +% \markdownEnd +% \bye +% ``````` +% % You can use the \mref{markinline} macro to input inline markdown content. % % \end{markdown} @@ -11921,6 +11961,8 @@ pdftex --shell-escape document.tex % The \mref{markinline} macro is subject to the same limitations as the % \mref{markdownBegin} and \mref{markdownEnd} macros. % +%#### Typesetting Markdown and YAML from external documents +% % 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 @@ -11934,7 +11976,7 @@ pdftex --shell-escape document.tex % \par % \begin{markdown} % -% This macro is not subject to the limitations of the +% The macro \mref{markdownInput} is not subject to the limitations of the % \mref{markdownBegin} and \mref{markdownEnd} macros. % % The following example plain \TeX{} code showcases the usage of the @@ -11946,7 +11988,7 @@ pdftex --shell-escape document.tex % \bye % ``````` % -% You can use the \mref{yamlInput} macro to include \acro{YAML} documents, +% You can use the \mref{yamlInput} macro to include \acro{YAML} documents. % similarly to how you might use the \mref{input} \TeX{} primitive to include % \TeX{} documents. The \mref{yamlInput} macro accepts a single parameter with % the filename of a \acro{YAML} document and expands to the result of the @@ -11964,7 +12006,7 @@ pdftex --shell-escape document.tex % \par % \begin{markdown} % -% This macro is also not subject to the limitations of the +% The macro \mref{yamlInput} is also not subject to the limitations of the % \mref{markdownBegin} and \mref{markdownEnd} macros. % % The following example plain \TeX{} code showcases the usage of the @@ -11985,6 +12027,8 @@ pdftex --shell-escape document.tex % \bye % ``````` % +%#### Typesetting TeX from inside Markdown and YAML documents +% % The \mref{markdownEscape} macro accepts a single parameter with the filename % of a \TeX{} document and executes the \TeX{} document in the middle of a % markdown document fragment. Unlike the `\input` built-in of \TeX, @@ -22049,12 +22093,12 @@ following text: % \begin{markdown} % % The \mdef{markdownReadAndConvert} macro implements the \mref{markdownBegin} -% macro. The first argument specifies the token sequence that will terminate -% the markdown input (\mref{markdownEnd} in the instance of the \mref{markdownBegin} -% macro) when the plain \TeX{} special characters have had their category -% changed to *other*. The second argument specifies the token sequence -% that will actually be inserted into the document, when the ending token -% sequence has been found. +% and \mref{yamlBegin} macros. The first argument specifies the token sequence +% that will terminate the markdown input when the plain \TeX{} special +% characters have had their category changed to *other*: \mref{markdownEnd} for +% the \mref{markdownBegin} macro and \mref{yamlEnd} for the \mref{yamlBegin} +% macro. The second argument specifies the token sequence that will actually be +% inserted into the document, when the ending token sequence has been found. % % \end{markdown} % \begin{macrocode} @@ -22073,6 +22117,11 @@ following text: |gdef|markdownBegin{% |markdownReadAndConvert{\markdownEnd}% {|markdownEnd}}% + |gdef|yamlBegin{% + |begingroup + |yamlSetup{jekyllData, expectJekyllData, ensureJekyllData}% + |markdownReadAndConvert{\yamlEnd}% + {|yamlEnd|endgroup}}% |endgroup % \end{macrocode} % \begin{markdown} From 481a01b7064ba9f0dc0aae120ff5424c80a6b664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 13:21:28 +0100 Subject: [PATCH 05/16] Add commands `\startyaml`, `\stopyaml`, and `\inputyaml` --- markdown.dtx | 166 +++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 141 insertions(+), 25 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 60d524976..f0117a81f 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11921,7 +11921,7 @@ pdftex --shell-escape document.tex % % ``` tex % \input markdown -% \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData} +% \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData} % \markdownBegin % title: _Hello **world** % author: John Doe @@ -12022,7 +12022,7 @@ pdftex --shell-escape document.tex % % ``` tex % \input markdown -% \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData} +% \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData} % \markdownInput{hello.yml} % \bye % ``````` @@ -23014,16 +23014,22 @@ following text: % \noindent It is expected that the special plain \TeX{} characters have the % expected category codes, when `\input`ting the file. % -%### 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} macro. +%### Typesetting Markdown and YAML +% +% The interface exposes the \mdef{startmarkdown}, \mdef{stopmarkdown}, +% \mdef{startyaml}, \mdef{stopyaml}, \mdef{inputmarkdown}, and \mdef{inputyaml} +% macros. +% +%#### Typesetting Markdown and YAML directly +% +% The \mref{startmarkdown} and \mref{stopmarkdown} macros are aliases for the +% macros \mref{markdownBegin} and \mref{markdownEnd} exposed by the plain +% \TeX{} interface. % % \end{markdown} % \begin{macrocode} \let\startmarkdown\relax \let\stopmarkdown\relax -\let\inputmarkdown\relax % \end{macrocode} % \par % \begin{markdown} @@ -23032,12 +23038,12 @@ following text: % \mref{stopmarkdown} macro to produce special effects before and after the % markdown block. % -% Note that the \mref{startmarkdown} and \mref{stopmarkdown} macros -% are subject to the same limitations as the \mref{markdownBegin} and -% \mref{markdownEnd} macros exposed by the plain \TeX{} interface. +% The macros \mref{startmarkdown} and \mref{stopmarkdown} are subject to the +% same limitations as the \mref{markdownBegin} and \mref{markdownEnd} macros. % % The following example \Hologo{ConTeXt} code showcases the usage of the % \mref{startmarkdown} and \mref{stopmarkdown} macros: +% % ``` tex % \usemodule[t][markdown] % \starttext @@ -23047,22 +23053,117 @@ following text: % \stoptext % ``````` % -% The \mref{inputmarkdown} macro accepts a single mandatory parameter -% containing the filename of a markdown document and expands to the result of -% the conversion of the input markdown document to plain \TeX{}. Unlike the -% \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro -% also accepts \Hologo{ConTeXt} interface options (see Section -% <#sec:context-options>) as its optional argument. These options will only -% influnce this markdown document. +% The \mref{startyaml} and \mref{stopyaml} macros are aliases for the macros +% \mref{yamlBegin} and \mref{yamlEnd} exposed by the plain \TeX{} interface. +% +% \end{yaml} +% \begin{macrocode} +\let\startyaml\relax +\let\stopyaml\relax +% \end{macrocode} +% \par +% \begin{yaml} +% +% You may prepend your own code to the \mref{startyaml} macro and redefine the +% \mref{stopyaml} macro to produce special effects before and after the yaml +% block. +% +% The macros \mref{startyaml} and \mref{stopyaml} are subject to the same +% limitations as the \mref{markdownBegin} and \mref{markdownEnd} macros. +% +% The following example \Hologo{ConTeXt} code showcases the usage of the +% \mref{startyaml} and \mref{stopyaml} macros: +% +% ``` tex +% \usemodule[t][markdown] +% \starttext +% \startyaml +% title: _Hello **world** +% author: John Doe +% \stopyaml +% \stoptext +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \usemodule[t][markdown] +% \starttext +% \setupyaml[jekyllData, expectJekyllData, ensureJekyllData] +% \startyaml +% title: _Hello **world** +% author: John Doe +% \stopyaml +% \stoptext +% ``````` +% +%#### Typesetting Markdown and YAML from external documents +% +% The \mref{inputmarkdown} macro aliases the macro \mref{markdownInput} exposed +% by the plain \TeX{} interface. +% +% \end{markdown} +% \begin{macrocode} +\let\inputmarkdown\relax +% \end{macrocode} +% \par +% \begin{markdown} +% +% Furthermore, the \mref{inputmarkdown} macro also accepts \Hologo{ConTeXt} +% interface options (see Section <#sec:context-options>) as its optional +% argument. These options will only influnce this markdown document. +% +% The following example \Hologo{ConTeXt} code showcases the usage of the +% \mref{inputmarkdown} macro: % -% The following example \LaTeX{} code showcases the usage of the -% \mref{markdownInput} macro: % ``` tex % \usemodule[t][markdown] % \starttext -% % ... % \inputmarkdown[smartEllipses]{hello.md} -% % ... +% \stoptext +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \usemodule[t][markdown] +% \starttext +% \setupmarkdown[smartEllipses] +% \inputmarkdown{hello.md} +% \stoptext +% ``````` +% +% The \mref{inputyaml} macro aliases the macro \mref{yamlInput} exposed by the +% plain \TeX{} interface. +% +% \end{markdown} +% \begin{macrocode} +\let\inputyaml\relax +% \end{macrocode} +% \par +% \begin{markdown} +% +% Furthermore, the \mref{inputyaml} macro also accepts \Hologo{ConTeXt} +% interface options (see Section <#sec:context-options>) as its optional +% argument. These options will only influnce this \acro{YAML} document. +% +% The following example \Hologo{ConTeXt} code showcases the usage of the +% \mref{inputyaml} macro: +% +% ``` tex +% \usemodule[t][markdown] +% \starttext +% \inputyaml[smartEllipses]{hello.yml} +% \stoptext +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \usemodule[t][markdown] +% \starttext +% \setupyaml[smartEllipses] +% \inputyaml{hello.yml} % \stoptext % ``````` % @@ -38606,9 +38707,9 @@ end % \begin{markdown} % %### Typesetting Markdown -% The \mref{inputmarkdown} macro is defined to accept an optional argument with -% options recognized by the \Hologo{ConTeXt} interface (see Section -% <#sec:context-options>). +% The \mref{inputmarkdown} and \mref{inputyaml} macros are defined to accept an +% optional argument with options recognized by the \Hologo{ConTeXt} interface +% (see Section <#sec:context-options>). % % \end{markdown} % \begin{macrocode} @@ -38622,11 +38723,17 @@ end \fi \markdownInput{#2}% \endgroup}% +\long\def\inputyaml{% + \dosingleempty + \doinputyaml}% +\long\def\doinputyaml[#1]#2{% + \doinputmarkdown[jekyllData, expectJekyllData, ensureJekyllData, #1]{#2}}% % \end{macrocode} % \par % \begin{markdown} % -% The \mref{startmarkdown} and \mref{stopmarkdown} macros are implemented using the +% The \mref{startmarkdown}, \mref{stopmarkdown}, \mref{startyaml}, and +% \mref{stopyaml} macros are implemented using the % \mref{markdownReadAndConvert} macro. % % In Knuth's \TeX, trailing spaces are removed very early on when a line is @@ -38660,6 +38767,15 @@ end |gdef|stopmarkdown{% |ctxlua{document.markdown_buffering = false}% |markdownEnd}% + |gdef|startyaml{% + |begingroup + |ctxlua{document.markdown_buffering = true}% + |setupyaml[jekyllData, expectJekyllData, ensureJekyllData]% + |markdownReadAndConvert{\stopyaml}% + {|stopyaml|endgroup}}% + |gdef|stopyaml{% + |ctxlua{document.markdown_buffering = false}% + |yamlEnd}% |endgroup % \end{macrocode} % \par From fb3bd85627ee56b89529beccbd99892d6f7e85b1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 14:21:18 +0100 Subject: [PATCH 06/16] Add LaTeX environment `yaml` and redefine command `\yamlInput` in LaTeX --- markdown.dtx | 179 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 141 insertions(+), 38 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index f0117a81f..c3d4743d5 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11911,7 +11911,7 @@ pdftex --shell-escape document.tex % ``` tex % \input markdown % \yamlBegin -% title: _Hello **world** +% title: _Hello_ **world** ... % author: John Doe % \yamlEnd % \bye @@ -11923,7 +11923,7 @@ pdftex --shell-escape document.tex % \input markdown % \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData} % \markdownBegin -% title: _Hello **world** +% title: _Hello_ **world** ... % author: John Doe % \markdownEnd % \bye @@ -22264,16 +22264,16 @@ pdflatex --shell-escape document.tex % \begin{markdown} % %### Typesetting Markdown -% The interface exposes the \envmdef{markdown} and \envmdef{markdown*} -% \LaTeX{} environments, and redefines the \mref{markinline} and -% \mref{markdownInput} commands. % -%#### The `markdown` and `markdown*` \LaTeX{} environments -% The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are used -% to typeset markdown document fragments. Both \LaTeX{} environments accept -% \LaTeX{} interface options (see Section <#sec:latex-options>) as the only -% argument. This argument is optional for the \envmref{markdown} environment -% and mandatory for the \envmref{markdown*} environment. +% The interface exposes the \envmdef{markdown}, \envmdef{markdown*}, and +% \envmdef{yaml} \LaTeX{} environments, and redefines the \mref{markinline}, +% \mref{markdownInput}, and \mref{yamlInput} commands. +% +%#### Typesetting Markdown and YAML directly +% +% The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are +% aliases for the macros \mref{markdownBegin} and \mref{markdownEnd} exposed +% by the plain \TeX{} interface. % % The \envmref{markdown*} environment has been deprecated and will be removed % in the next major version of the Markdown package. @@ -22285,26 +22285,25 @@ pdflatex --shell-escape document.tex % \end{macrocode} % \markdownBegin % -% You may prepend your own code to the \mdef{markdown} macro and append your own -% code to the \mref{markdownEnd} macro to produce special effects before and after -% the \envmref{markdown} \LaTeX{} environment (and likewise for the starred -% version). +% Furthermore, both environments accept \LaTeX{} interface options (see Section +% <#sec:latex-options>) as the only argument. This argument is optional for the +% \envmref{markdown} environment and mandatory for the \envmref{markdown*} +% environment. % -% Note that the \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are -% subject to the same limitations as the \mref{markdownBegin} and \mref{markdownEnd} -% macros exposed by the plain \TeX{} interface. +% The \envmref{markdown} and \envmref{markdown*} environments are +% subject to the same limitations as the \mref{markdownBegin} and +% \mref{markdownEnd} macros. % % The following example \LaTeX{} code showcases the usage of the % \envmref{markdown} and \envmref{markdown*} environments: +% % ``` tex % \documentclass{article} \documentclass{article} % \usepackage{markdown} \usepackage{markdown} % \begin{document} \begin{document} -% \% ... \% ... % \begin{markdown}[smartEllipses] \begin{markdown*}{smartEllipses} % _Hello_ **world** ... _Hello_ **world** ... % \end{markdown} \end{markdown*} -% \% ... \% ... % \end{document} \end{document} % ``````` % @@ -22333,11 +22332,14 @@ pdflatex --shell-escape document.tex % % Specifically, the \mref{markdown} macro must appear at the end of the % replacement text and must be followed by text that has not yet been ingested -% by \TeX's input processor. Furthermore, using the \mref{markdownEnd} macro is +% by \TeX's input processor. +% +% Furthermore, using the \mref{markdownEnd} macro is % optional and only makes a difference if you redefined it to produce special -% effects before and after the \envmref{markdown} \LaTeX{} environment. Lastly, -% you can't nest the other environments. For example, the following definition -% is incorrect: +% effects before and after the \envmref{markdown} \LaTeX{} environment. +% +% Lastly, you can't nest the other environments. For example, the following +% definition would be incorrect: % % ``` tex % \newenvironment{bar}{\begin{foo}}{\end{foo}} @@ -22350,34 +22352,121 @@ pdflatex --shell-escape document.tex % \newenvironment{bar}{\markdown[some, options]}{\markdownEnd} % ``` % +% The \envmref{yaml} \LaTeX{} environment is an alias for the macros +% \mref{yamlBegin} and \mref{yamlEnd} exposed by the plain \TeX{} interface. +% +% \end{markdown} +% \begin{macrocode} +\newenvironment{yaml}\relax\relax +% \end{macrocode} +% \begin{markdown} +% +% Furthermore, the environment accepts \LaTeX{} interface options (see Section +% <#sec:latex-options>) as the only optional argument. +% +% The \envmref{yaml} environment is subject to the same limitations as +% the \mref{markdownBegin} and \mref{markdownEnd} macros. +% +% The following example \LaTeX{} code showcases the usage of the +% \envmref{yaml} environment: +% +% ``` tex +% \documentclass{article} +% \usepackage{markdown} +% \begin{document} +% \begin{yaml}[smartEllipses] +% title: _Hello_ **world** ... +% author: John Doe +% \end{yaml} +% \end{document} +% ``````` +% % \end{markdown} % \markdownBegin % -%#### The `\markinline` and `\markdownInput` macros +% The above code has the same effect as the below code: +% +% ``` tex +% \documentclass{article} +% \usepackage{markdown} +% \begin{document} +% \begin{markdown}[ +% jekyllData, +% expectJekyllData, +% ensureJekyllData, +% smartEllipses, +% ] +% title: _Hello_ **world** ... +% author: John Doe +% \end{markdown} +% \end{document} +% ``````` +% +% You can't directly extend the \envmref{yaml} \LaTeX{} environment by using it +% in other environments. However, you can work around this limitation by using +% the \mref{yaml} and \mref{yamlEnd} macros directly in the definition, +% similarly to the \mref{markdown} and \mref{markdownEnd} macros described +% previously. +% % The \mref{markinline} macro accepts a single mandatory parameter containing % inline markdown content and expands to the result of the conversion of the % input markdown document to plain \TeX{}. Unlike the \mref{markinline} macro % provided by the plain \TeX{} interface, this macro also accepts \LaTeX{} % interface options (see Section <#sec:latex-options>) as its optional -% argument. These options will only influnce this markdown content. +% argument. These options will only influence this markdown content. +% +%#### Typesetting Markdown and YAML from external documents % % The \mref{markdownInput} macro accepts a single mandatory parameter containing % the filename of a markdown document and expands to the result of the % conversion of the input markdown document to plain \TeX{}. Unlike the % \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro % also accepts \LaTeX{} interface options (see Section <#sec:latex-options>) -% as its optional argument. These options will only influnce this markdown +% as its optional argument. These options will only influence this markdown % document. % % The following example \LaTeX{} code showcases the usage of the % \mref{markdownInput} macro: +% % ``` tex % \documentclass{article} % \usepackage{markdown} % \begin{document} -% % ... % \markdownInput[smartEllipses]{hello.md} -% % ... +% \end{document} +% ``````` +% +% The \mref{yamlInput} macro accepts a single mandatory parameter containing +% the filename of a \acro{YAML} document and expands to the result of the +% conversion of the input \acro{YAML} document to plain \TeX{}. Unlike the +% \mref{yamlInput} macro provided by the plain \TeX{} interface, this macro +% also accepts \LaTeX{} interface options (see Section <#sec:latex-options>) +% as its optional argument. These options will only influence this \acro{YAML} +% document. +% +% The following example \LaTeX{} code showcases the usage of the +% \mref{yamlInput} macro: +% +% ``` tex +% \documentclass{article} +% \usepackage{markdown} +% \begin{document} +% \yamlInput[smartEllipses]{hello.yml} +% \end{document} +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \documentclass{article} +% \usepackage{markdown} +% \begin{document} +% \markdownInput[ +% jekyllData, +% expectJekyllData, +% ensureJekyllData, +% smartEllipses, +% ]{hello.yml} % \end{document} % ``````` % @@ -23078,7 +23167,7 @@ following text: % \usemodule[t][markdown] % \starttext % \startyaml -% title: _Hello **world** +% title: _Hello_ **world** ... % author: John Doe % \stopyaml % \stoptext @@ -23091,7 +23180,7 @@ following text: % \starttext % \setupyaml[jekyllData, expectJekyllData, ensureJekyllData] % \startyaml -% title: _Hello **world** +% title: _Hello_ **world** ... % author: John Doe % \stopyaml % \stoptext @@ -23111,7 +23200,7 @@ following text: % % Furthermore, the \mref{inputmarkdown} macro also accepts \Hologo{ConTeXt} % interface options (see Section <#sec:context-options>) as its optional -% argument. These options will only influnce this markdown document. +% argument. These options will only influence this markdown document. % % The following example \Hologo{ConTeXt} code showcases the usage of the % \mref{inputmarkdown} macro: @@ -23145,7 +23234,7 @@ following text: % % Furthermore, the \mref{inputyaml} macro also accepts \Hologo{ConTeXt} % interface options (see Section <#sec:context-options>) as its optional -% argument. These options will only influnce this \acro{YAML} document. +% argument. These options will only influence this \acro{YAML} document. % % The following example \Hologo{ConTeXt} code showcases the usage of the % \mref{inputyaml} macro: @@ -36537,9 +36626,10 @@ end % \begin{markdown} % % The \mdef{markdownInputPlainTeX} macro is used to store the original plain -% \TeX{} implementation of the \mref{markdownInput} macro. The \mref{markdownInput} -% macro is then redefined to accept an optional argument with options recognized by -% the \LaTeX{} interface (see Section <#sec:latex-options>). +% \TeX{} implementation of the \mref{yamlInput} macro. The \mref{markdownInput} +% and \mref{yamlInput} macros are then redefined to accept an optional argument +% with options recognized by the \LaTeX{} interface (see Section +% <#sec:latex-options>). % % \end{markdown} % \begin{macrocode} @@ -36549,12 +36639,17 @@ end \markdownSetup{#1}% \markdownInputPlainTeX{#2}% \endgroup}% +\renewcommand\yamlInput[2][]{% + \begingroup + \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData, #1}% + \markdownInputPlainTeX{#2}% + \endgroup}% % \end{macrocode} % \par % \begin{markdown} % -% The \envmref{markdown}, and \envmref{markdown*} \LaTeX{} environments are -% implemented using the \mref{markdownReadAndConvert} macro. +% The \envmref{markdown}, \envmref{markdown*}, and \envmref{yaml} \LaTeX{} +% environments are implemented using the \mref{markdownReadAndConvert} macro. % % \end{markdown} % \begin{macrocode} @@ -36693,6 +36788,14 @@ end { markdown* } } { \markdownEnd } +\renewenvironment + { yaml } + { + \group_begin: + \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData}% + \markdown + } + { \yamlEnd } \msg_new:nnn { markdown } { latex-markdown-star-deprecated } From 6be3825784883d89779123bd00db24eaeecd3f6a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 14:27:28 +0100 Subject: [PATCH 07/16] Update `CHANGES.md` --- CHANGES.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES.md b/CHANGES.md index 7b8969dd5..25d8ad735 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -17,6 +17,11 @@ Development: [matrix-514]: https://matrix.to/#/!UeAwznpYwwsinVTetR:matrix.org/$TTc-m7B5NSdsLBNNyIuFWQ-u2nOZ03lJ5js88hnyFiU?via=matrix.org&via=im.f3l.de +- Add first-class support for YAML documents. (#452, #473, #524) + - Add plain TeX macros `\yamlSetup`, `\yamlInput`, `\yamlBegin`, and `\yamlEnd`. + - Add LaTeX environment `yaml` and redefine command `\yamlInput` for LaTeX. + - Add ConTeXt commands `\setupyaml`, `\inputyaml`, `\startyaml`, and `\stopyaml`. + Documentation: - Document LaTeX hooks. (#464, #507) From cc64ba12595ef3069cf344339f8bfdff3b276adc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 14:40:03 +0100 Subject: [PATCH 08/16] Fix overlong line --- markdown.dtx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/markdown.dtx b/markdown.dtx index c3d4743d5..2bb378117 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -38830,7 +38830,8 @@ end \dosingleempty \doinputyaml}% \long\def\doinputyaml[#1]#2{% - \doinputmarkdown[jekyllData, expectJekyllData, ensureJekyllData, #1]{#2}}% + \doinputmarkdown + [jekyllData, expectJekyllData, ensureJekyllData, #1]{#2}}% % \end{macrocode} % \par % \begin{markdown} From e149ee43fd6e8962debaeb26659e7fa0e89841b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 15:01:38 +0100 Subject: [PATCH 09/16] Mark expl3 code as expl3 --- markdown.dtx | 2 -- 1 file changed, 2 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 2bb378117..94a08a25c 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -23282,7 +23282,6 @@ following text: \@@_setup:n { #1 } } -\ExplSyntaxOff % \end{macrocode} % \begin{markdown} % @@ -23304,7 +23303,6 @@ following text: % % \end{markdown} % \begin{macrocode} -\ExplSyntaxOn \cs_new:Nn \@@_caseless:N { \regex_replace_all:nnN From b48ddc442f0206336873892d392014f78abf711a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 15:14:12 +0100 Subject: [PATCH 10/16] Fix a typo in the documentation code --- markdown.dtx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 94a08a25c..3266ff217 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -23145,13 +23145,13 @@ following text: % The \mref{startyaml} and \mref{stopyaml} macros are aliases for the macros % \mref{yamlBegin} and \mref{yamlEnd} exposed by the plain \TeX{} interface. % -% \end{yaml} +% \end{markdown} % \begin{macrocode} \let\startyaml\relax \let\stopyaml\relax % \end{macrocode} % \par -% \begin{yaml} +% \begin{markdown} % % You may prepend your own code to the \mref{startyaml} macro and redefine the % \mref{stopyaml} macro to produce special effects before and after the yaml From 7e8113537814e93b401f1e3cca7dfe4e6566c02b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 15:14:46 +0100 Subject: [PATCH 11/16] Apply suggestions from the review --- markdown.dtx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/markdown.dtx b/markdown.dtx index 3266ff217..325cdd17b 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -36639,7 +36639,7 @@ end \endgroup}% \renewcommand\yamlInput[2][]{% \begingroup - \markdownSetup{jekyllData, expectJekyllData, ensureJekyllData, #1}% + \yamlSetup{jekyllData, expectJekyllData, ensureJekyllData, #1}% \markdownInputPlainTeX{#2}% \endgroup}% % \end{macrocode} From c690955a029279c4ce4caf0a32dd86d6d8d3ef27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 15:46:07 +0100 Subject: [PATCH 12/16] Fix ConTeXt example --- examples/context-mkiv.tex | 18 +++++++----------- 1 file changed, 7 insertions(+), 11 deletions(-) diff --git a/examples/context-mkiv.tex b/examples/context-mkiv.tex index f038377e0..34b6b3509 100644 --- a/examples/context-mkiv.tex +++ b/examples/context-mkiv.tex @@ -58,30 +58,26 @@ \starttext % Set and typeset the document metadata using a YAML metadata block. -\def\doctitle#1{\gdef\@title{#1}} -\def\author#1{\gdef\@author{#1}} -\def\date#1{\gdef\@date{#1}} - \setupyaml [ jekyllDataRenderers = { - title = {\doctitle{#1}}, - author = {\author{#1}}, - date = {\date{#1}}, + title = {\gdef\doctitle{#1}}, + author = {\gdef\author{#1}}, + date = {\gdef\date{#1}}, }, renderers = { jekyllDataEnd = {% \startalignment[center] \blank[force,2*big] - {\tfd \@title} + {\tfd \doctitle} \blank[3*medium] - {\tfa \@author} + {\tfa \author} \blank[2*medium] - {\tfa \@date} + {\tfa \date} \blank[3*medium] \stopalignment }, - } + }, ] \startyaml From d3ad615c832fdeb5fae2f5fb42bff3f58d762914 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 16:54:12 +0100 Subject: [PATCH 13/16] Add `\endgroup` after `\end{yaml}` --- markdown.dtx | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 325cdd17b..f5e99e157 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11897,7 +11897,7 @@ pdftex --shell-escape document.tex % \end{markdown} % \begin{macrocode} \let\yamlBegin\relax -\let\yamlEnd\relax +\let\yamlEnd{\markdownEnd\endgroup} % \end{macrocode} % \par % \begin{markdown} @@ -22121,7 +22121,7 @@ following text: |begingroup |yamlSetup{jekyllData, expectJekyllData, ensureJekyllData}% |markdownReadAndConvert{\yamlEnd}% - {|yamlEnd|endgroup}}% + {|yamlEnd}}% |endgroup % \end{macrocode} % \begin{markdown} @@ -22331,12 +22331,9 @@ pdflatex --shell-escape document.tex % ``` % % Specifically, the \mref{markdown} macro must appear at the end of the -% replacement text and must be followed by text that has not yet been ingested -% by \TeX's input processor. -% -% Furthermore, using the \mref{markdownEnd} macro is -% optional and only makes a difference if you redefined it to produce special -% effects before and after the \envmref{markdown} \LaTeX{} environment. +% replacement before-text and must be followed by text that has not yet been +% ingested by \TeX's input processor. The \mref{markdownEnd} macro must be used +% in or after the replacement after-text. % % Lastly, you can't nest the other environments. For example, the following % definition would be incorrect: @@ -23153,9 +23150,9 @@ following text: % \par % \begin{markdown} % -% You may prepend your own code to the \mref{startyaml} macro and redefine the -% \mref{stopyaml} macro to produce special effects before and after the yaml -% block. +% You may prepend your own code to the \mref{startyaml} macro and append your +% own code to the \mref{stopyaml} macro to produce special effects before and +% after the \acro{YAML} document. % % The macros \mref{startyaml} and \mref{stopyaml} are subject to the same % limitations as the \mref{markdownBegin} and \mref{markdownEnd} macros. @@ -38874,7 +38871,7 @@ end |ctxlua{document.markdown_buffering = true}% |setupyaml[jekyllData, expectJekyllData, ensureJekyllData]% |markdownReadAndConvert{\stopyaml}% - {|stopyaml|endgroup}}% + {|stopyaml}}% |gdef|stopyaml{% |ctxlua{document.markdown_buffering = false}% |yamlEnd}% From e0989f60409ee154970ab7cf5ef7a386ab32444c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 17:20:24 +0100 Subject: [PATCH 14/16] Fix a typo --- markdown.dtx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/markdown.dtx b/markdown.dtx index f5e99e157..2adb069a0 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -11897,7 +11897,7 @@ pdftex --shell-escape document.tex % \end{markdown} % \begin{macrocode} \let\yamlBegin\relax -\let\yamlEnd{\markdownEnd\endgroup} +\def\yamlEnd{\markdownEnd\endgroup} % \end{macrocode} % \par % \begin{markdown} From 65a5b7f7f561de025bdeb289cacc8b29b8f1a7c9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 17:29:39 +0100 Subject: [PATCH 15/16] Update `Makefile` --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 64e4e5618..b67ec6530 100644 --- a/Makefile +++ b/Makefile @@ -157,7 +157,7 @@ $(LIBRARIES): force # This target typesets the manual. $(TECHNICAL_DOCUMENTATION): $(DTXARCHIVE) $(TECHNICAL_DOCUMENTATION_RESOURCES) latexmk -silent $< || (cat $(basename $@).log 1>&2; exit 1) - test `tail $(basename $<).log | sed -rn 's/.*\(([0-9]*) pages.*/\1/p'` -ge 380 + test `tail $(basename $<).log | sed -rn 's/.*\(([0-9]*) pages.*/\1/p'` -ge 450 # This pseudotarget continuously typesets the manual. preview: $(DTXARCHIVE) $(TECHNICAL_DOCUMENTATION_RESOURCES) From 62b7d64ad3fcb08c19a0f0c1a52884d853582cde Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Star=C3=BD=20Novotn=C3=BD?= Date: Mon, 28 Oct 2024 20:27:03 +0100 Subject: [PATCH 16/16] Be more concrete in the documentation --- markdown.dtx | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/markdown.dtx b/markdown.dtx index 2adb069a0..3c7add0f4 100644 --- a/markdown.dtx +++ b/markdown.dtx @@ -22332,8 +22332,12 @@ pdflatex --shell-escape document.tex % % Specifically, the \mref{markdown} macro must appear at the end of the % replacement before-text and must be followed by text that has not yet been -% ingested by \TeX's input processor. The \mref{markdownEnd} macro must be used -% in or after the replacement after-text. +% ingested by \TeX's input processor. +% +% Furthermore, using the \mref{markdownEnd} macro in of after the replacement +% after-text is optional and only makes a difference if you redefined it to +% produce special effects before and after the \envmref{markdown} \LaTeX{} +% environment. % % Lastly, you can't nest the other environments. For example, the following % definition would be incorrect: @@ -22403,7 +22407,8 @@ pdflatex --shell-escape document.tex % in other environments. However, you can work around this limitation by using % the \mref{yaml} and \mref{yamlEnd} macros directly in the definition, % similarly to the \mref{markdown} and \mref{markdownEnd} macros described -% previously. +% previously. Unlike with the \mref{markdown} and \mref{markdownEnd} macros, +% The \mref{yamlEnd} macro _must_ be used in or after the replacement after-text. % % The \mref{markinline} macro accepts a single mandatory parameter containing % inline markdown content and expands to the result of the conversion of the