diff options
author | Norbert Preining <norbert@preining.info> | 2024-05-01 03:00:54 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2024-05-01 03:00:54 +0000 |
commit | 6ac3dbed4b71022bd6bb0cc25e8fc3df81198498 (patch) | |
tree | 74689e5368262d351f68fb5d1f0fbea88a3af701 /macros/generic | |
parent | 3bb814fe836cd59db56f2f5d07f69cb531ed25e0 (diff) |
CTAN sync 202405010300
Diffstat (limited to 'macros/generic')
-rw-r--r-- | macros/generic/markdown/CHANGES.md | 22 | ||||
-rw-r--r-- | macros/generic/markdown/README.md | 37 | ||||
-rw-r--r-- | macros/generic/markdown/VERSION | 2 | ||||
-rw-r--r-- | macros/generic/markdown/examples/context-mkiv.tex | 13 | ||||
-rw-r--r-- | macros/generic/markdown/examples/latex-luatex.tex | 29 | ||||
-rw-r--r-- | macros/generic/markdown/examples/latex-pdftex.tex | 18 | ||||
-rw-r--r-- | macros/generic/markdown/markdown.dtx | 767 | ||||
-rw-r--r-- | macros/generic/markdown/markdown.html | 2 | ||||
-rw-r--r-- | macros/generic/markdown/markdown.pdf | bin | 1099548 -> 1116505 bytes |
9 files changed, 690 insertions, 200 deletions
diff --git a/macros/generic/markdown/CHANGES.md b/macros/generic/markdown/CHANGES.md index 614cef6912..3ea1c8c837 100644 --- a/macros/generic/markdown/CHANGES.md +++ b/macros/generic/markdown/CHANGES.md @@ -1,8 +1,26 @@ # Changes -## 3.5.0 +## 3.5.0 (2024-04-29) -## 3.4.3 +Development: + +- Add `\markinline` plain TeX command. (#300, #439) +- Support incremental definitions of token renderers and renderer prototypes + in the `\markdownSetup` command. + (#232, #435, 540a83c0, [matrix.org][matrix-435], #437, #438, + contributed by @eg9, @gucci-on-fleek, and @Skillmon + [on TeX StackExchange][tse-716400]) + + [matrix-435]: https://matrix.to/#/!UeAwznpYwwsinVTetR:matrix.org/$k4ky6I-uvxdp8ipVlHvef5JXfIfPQvFtXOAD_ogF2uU?via=matrix.org&via=im.f3l.de + [tse-716400]: https://tex.stackexchange.com/questions/716362/convert-control-sequence-with-a-variable-number-of-parameters-into-a-token-list/716400#716400 + +Default Renderer Prototypes: + +- Add default renderers for unnumbered sections in LaTeX. + (#401, istqborg/istqb_product_base#23, #430, reported by @felinecrp, + sponsored by @istqborg) + +## 3.4.3 (2024-04-04) Fixes: diff --git a/macros/generic/markdown/README.md b/macros/generic/markdown/README.md index 76ad39d740..69fdc4ab30 100644 --- a/macros/generic/markdown/README.md +++ b/macros/generic/markdown/README.md @@ -193,14 +193,14 @@ For further information, consult one of the following: - [Markdown 2.17.1: What's New, What's Next?][tb135], - [Attributes in Markdown][tb136], - Markdown 3 at TUG 2023: Reflections from the Q&A session ([preprint][tb138]), and - - Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching ([work in progress][tb139]). + - Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching ([preprint][tb139]). 5. Journal articles published by [CSTUG Bulletin][csbul] (in Czech and Slovak): - [Rendering Markdown inside TeX Documents][10.5300/2016-1-4/78], - [Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX][10.5300/2020-1-2/48], - [Markdown 2.10.0: LaTeX Themes & Snippets][10.5300/2021-1-4/76], - [Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility][10.5300/2021-1-4/83], - [High-Level Languages for TeX][10.5300/2022-1-4/35], and - - Markdown 3: What's New, What's Next? ([preprint][10.5300/2023-?-?/??]). + - [Markdown 3: What's New, What's Next?][10.5300/2023-3-4/111]. 6. Talks: - [Five Years of Markdown in LaTeX: What, Why, How, and Whereto][pv212-fall2020] (in Czech), - [Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX][tb131-video] ([slides][tb131-slides]), @@ -219,15 +219,15 @@ For further information, consult one of the following: [overleaf-5]: https://www.overleaf.com/latex/examples/writing-posters-with-markdown/jtbgmmgqrqmh "Writing Posters with Markdown" [overleaf-6]: https://www.overleaf.com/latex/examples/using-markdown-in-latex-documents/whdrnpcpnwrm "Using Markdown in LaTeX documents" - [tb119]: https://www.tug.org/TUGboat/tb38-2/tb119novotny.pdf "Using Markdown inside TeX documents" - [tb124]: https://www.tug.org/TUGboat/tb40-1/tb124novotny-markdown.pdf "Markdown 2.7.0: Towards lightweight markup in TeX" - [tb129]: https://www.tug.org/TUGboat/tb41-3/tb129novotny-frozen.pdf "Making Markdown into a Microwave Meal" - [tb131]: https://www.tug.org/TUGboat/tb42-2/tb131novotny-markdown.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" - [tb133]: https://www.tug.org/TUGboat/tb43-1/tb133novotny-markdown.pdf "Markdown 2.15.0: What's New?" - [tb135]: https://www.tug.org/TUGboat/tb43-3/tb135novotny-markdown.pdf "Markdown 2.17.1: What's New, What's Next?" - [tb136]: https://www.tug.org/TUGboat/tb44-1/tb136novotny-markdown-attr.pdf "Attributes in Markdown" - [tb138]: https://www.overleaf.com/read/mjghwhrbgmfj "Markdown 3 at TUG 2023: Reflections from the Q&A session" - [tb139]: https://github.com/witiko/fast-regression-testing/releases/download/latest/main.pdf "Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching" + [tb119]: https://www.tug.org/TUGboat/tb38-2/tb119novotny.pdf "Using Markdown inside TeX documents" + [tb124]: https://www.tug.org/TUGboat/tb40-1/tb124novotny-markdown.pdf "Markdown 2.7.0: Towards lightweight markup in TeX" + [tb129]: https://www.tug.org/TUGboat/tb41-3/tb129novotny-frozen.pdf "Making Markdown into a Microwave Meal" + [tb131]: https://www.tug.org/TUGboat/tb42-2/tb131novotny-markdown.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" + [tb133]: https://www.tug.org/TUGboat/tb43-1/tb133novotny-markdown.pdf "Markdown 2.15.0: What's New?" + [tb135]: https://www.tug.org/TUGboat/tb43-3/tb135novotny-markdown.pdf "Markdown 2.17.1: What's New, What's Next?" + [tb136]: https://www.tug.org/TUGboat/tb44-1/tb136novotny-markdown-attr.pdf "Attributes in Markdown" + [tb138]: https://www.overleaf.com/read/mjghwhrbgmfj "Markdown 3 at TUG 2023: Reflections from the Q&A session" + [tb139]: https://github.com/Witiko/fast-regression-testing/releases/download/latest/tb139starynovotny-testing.pdf "Fast Regression Testing of TeX Packages: The Unreasonable Effectiveness of Batching" [tb131-slides]: https://tug.org/tug2021/assets/pdf/tug2021-novotny-slides.pdf "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" [tb131-video]: https://youtu.be/i2GJMnLCZls "Markdown 2.10.0: LaTeX Themes & Snippets, Two Flavors of Comments, and LuaMetaTeX" @@ -239,13 +239,13 @@ For further information, consult one of the following: [tb137-slides]: https://tug.org/tug2023/files/sa-03-novotny-markdown3/novotny-markdown3-slides.pdf "Markdown 3: What's New, What's Next?" [tb137-video]: https://youtu.be/U8XjTOhJkg0 "Markdown 3: What's New, What's Next?" - [10.5300/2016-1-4/78]: https://www.doi.org/10.5300/2016-1-4/78 "Rendering Markdown inside TeX Documents" - [10.5300/2020-1-2/48]: https://www.doi.org/10.5300/2020-1-2/48 "Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX" - [10.5300/2021-1-4/76]: https://www.doi.org/10.5300/2021-1-4/76 "Markdown 2.10.0: LaTeX Themes & Snippets" - [10.5300/2021-1-4/83]: https://www.doi.org/10.5300/2021-1-4/83 "Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility" - [10.5300/2022-1-4/35]: https://www.doi.org/10.5300/2022-1-4/35 "High-Level Languages for TeX" + [10.5300/2016-1-4/78]: https://www.doi.org/10.5300/2016-1-4/78 "Rendering Markdown inside TeX Documents" + [10.5300/2020-1-2/48]: https://www.doi.org/10.5300/2020-1-2/48 "Markdown 2.8.1: Boldly Unto the Throne of Lightweight Markup in TeX" + [10.5300/2021-1-4/76]: https://www.doi.org/10.5300/2021-1-4/76 "Markdown 2.10.0: LaTeX Themes & Snippets" + [10.5300/2021-1-4/83]: https://www.doi.org/10.5300/2021-1-4/83 "Direct Typesetting of Various Document Formats in TeX Using the Pandoc Utility" + [10.5300/2022-1-4/35]: https://www.doi.org/10.5300/2022-1-4/35 "High-Level Languages for TeX" - [10.5300/2023-?-?/??]: https://github.com/witiko/markdown-3-whats-new-whats-next/releases/download/latest/main.pdf "Markdown 3: What's New, What's Next?" + [10.5300/2023-3-4/111]: https://www.doi.org/10.5300/2023-3-4/111 "Markdown 3: What's New, What's Next?" [pv212-fall2020]: https://is.muni.cz/elearning/io/?qurl=%2Fel%2Ffi%2Fpodzim2020%2FPV212%2Findex.qwarp;prejit=5595952 @@ -274,7 +274,7 @@ Acknowledgements | [<img width="150" src="https://www.fi.muni.cz/images/fi-logo.png">][fimu] | I gratefully acknowledge the funding from the [Faculty of Informatics][fimu] at the [Masaryk University][mu] in Brno, Czech Republic, for the development of the Markdown package in projects [MUNI/33/12/2015][], [MUNI/33/1784/2020][], [MUNI/33/0776/2021][], [MUNI/33/1654/2022][], and [MUNI/33/1658/2022][]. | | [<img width="150" src="https://cdn.overleaf.com/img/ol-brand/overleaf_og_logo.png">][overleaf] | Extensive user documentation for the Markdown package was kindly written by [Lian Tze Lim][liantze] and published by [Overleaf][]. | | [<img width="150" src="https://pbs.twimg.com/profile_images/1004769879319334912/6Bh1UthD.jpg">][omedym] | Support for content slicing (Lua options [`shiftHeadings`][option-shift-headings] and [`slice`][option-slice]) and pipe tables (Lua options [`pipeTables`][option-pipe-tables] and [`tableCaptions`][option-table-captions]) was graciously sponsored by [David Vins][dvins] and [Omedym][]. | -| [<img width="150" src="https://www.istqb.org/static/istqb-logo-1b043e800a580724ad223567f9ea57c0.png">][istqb] | Fixes for issues [#359][issue-359], [#368][issue-368], and [#424][issue-424] were graciously sponsored by the [International Software Testing Qualifications Board (ISTQB)][istqb]. | +| [<img width="150" src="https://www.istqb.org/static/istqb-logo-1b043e800a580724ad223567f9ea57c0.png">][istqb] | Fixes for issues [#359][issue-359], [#368][issue-368], [#401][issue-401], and [#424][issue-424] were graciously sponsored by the [International Software Testing Qualifications Board (ISTQB)][istqb]. | [dvins]: https://github.com/dvins "David Vins" [fimu]: https://www.fi.muni.cz/index.html.en "Faculty of Informatics, Masaryk University" @@ -284,6 +284,7 @@ Acknowledgements [issue-359]: https://github.com/witiko/markdown/issues/359 "First item of a fancy list forms a separate list" [issue-368]: https://github.com/witiko/markdown/issues/368 "Tables nested in list items have empty lines" + [issue-401]: https://github.com/witiko/markdown/issues/401 "Create an unnumbered section" [issue-424]: https://github.com/witiko/markdown/issues/424 "E-mail addresses are incorrectly interpreted as bracketed citations" [option-pipe-tables]: https://mirrors.ctan.org/macros/generic/markdown/markdown.html#pipe-tables "Markdown Package User Manual" diff --git a/macros/generic/markdown/VERSION b/macros/generic/markdown/VERSION index d13fdfa34f..e4e9a98451 100644 --- a/macros/generic/markdown/VERSION +++ b/macros/generic/markdown/VERSION @@ -1 +1 @@ -3.4.3-0-ge2c6be1a (2024-04-04) +3.5.0-0-gfd01a252 (2024-04-29) diff --git a/macros/generic/markdown/examples/context-mkiv.tex b/macros/generic/markdown/examples/context-mkiv.tex index 8b000e43ed..6cb185802a 100644 --- a/macros/generic/markdown/examples/context-mkiv.tex +++ b/macros/generic/markdown/examples/context-mkiv.tex @@ -72,16 +72,15 @@ kpse.set_program_name("luatex") \catcode`\%=14\relax \catcode`\#=6\relax -% Typeset some further examples with inline markdown text. +% Besides inputting external files, Markdown text can we written directly +% into a LaTeX document. Markdown text and LaTeX code can be freely combined. \startmarkdown -Here are some non-ASCII characters: *ěščřžýáíé* -and ConTeXt special characters: *|*. +This is a paragraph of *Markdown text* with inline `\LaTeX`{=tex} code. -Here is a hard line break that we inserted directly from the TeX source -by typing two spaces at the end of a line. -This is stretching TeX's abilities and is only supported in ConTeXt MkIV -and later. +``` {=tex} +This is a paragraph of \LaTeX{} code with inline \markinline{*Markdown text*}. +``` \stopmarkdown diff --git a/macros/generic/markdown/examples/latex-luatex.tex b/macros/generic/markdown/examples/latex-luatex.tex index 5aa7c85d7d..51be09c1f6 100644 --- a/macros/generic/markdown/examples/latex-luatex.tex +++ b/macros/generic/markdown/examples/latex-luatex.tex @@ -49,8 +49,33 @@ date: \today \catcode`\%=14\relax \catcode`\#=6\relax -% Typeset some further examples with inline markdown text. +% Besides inputting external files, Markdown text can we written directly +% into a LaTeX document. Markdown text and LaTeX code can be freely combined. \begin{markdown} -Here are some non-ASCII characters: *ěščřžýáíé*. +This is a paragraph of *Markdown text* with inline `\LaTeX`{=tex} code. + +``` {=tex} +This is a paragraph of \LaTeX{} code with inline \markinline{*Markdown text*}. +``` +\end{markdown} + +% Besides YAML, LaTeX, and Markdown, you can also type HTML in your documents. +\begin{markdown} +Here is some <b>HTML code</b> mixed *with Markdown*. In `\TeX`{=tex}, the HTML +code will be silently ignored, whereas in `\TeX`{=tex}4ht, the HTML code will +be passed through to the output: + +<table border="1"> + <tr> + <td>Emil</td> + <td>Tobias</td> + <td>Linus</td> + </tr> + <tr> + <td>16</td> + <td>14</td> + <td>10</td> + </tr> +</table> \end{markdown} \end{document} diff --git a/macros/generic/markdown/examples/latex-pdftex.tex b/macros/generic/markdown/examples/latex-pdftex.tex index 7d188d75f2..34f78707c3 100644 --- a/macros/generic/markdown/examples/latex-pdftex.tex +++ b/macros/generic/markdown/examples/latex-pdftex.tex @@ -50,15 +50,21 @@ date: \today \catcode`\%=14\relax \catcode`\#=6\relax -% Typeset some further examples with inline markdown text. +% Besides inputting external files, Markdown text can we written directly +% into a LaTeX document. Markdown text and LaTeX code can be freely combined. \begin{markdown} -Here are some non-ASCII characters: *ěščřžýáíé*. +This is a paragraph of *Markdown text* with inline `\LaTeX`{=tex} code. + +``` {=tex} +This is a paragraph of \LaTeX{} code with inline \markinline{*Markdown text*}. +``` \end{markdown} -\begin{markdown}[hybrid] -Here is some <b>HTML code</b> mixed *with Markdown*. In \TeX, the HTML code -will be silently ignored, whereas in \TeX 4ht, the HTML code will be passed -through to the output: +% Besides YAML, LaTeX, and Markdown, you can also type HTML in your documents. +\begin{markdown} +Here is some <b>HTML code</b> mixed *with Markdown*. In `\TeX`{=tex}, the HTML +code will be silently ignored, whereas in `\TeX`{=tex}4ht, the HTML code will +be passed through to the output: <table border="1"> <tr> diff --git a/macros/generic/markdown/markdown.dtx b/macros/generic/markdown/markdown.dtx index dd4c7367fb..bbbd06e8bb 100644 --- a/macros/generic/markdown/markdown.dtx +++ b/macros/generic/markdown/markdown.dtx @@ -683,6 +683,12 @@ abbr { \endgroup %</techdoc-block-diagram> %<*techdoc-bibliography> +@online{starynovotny24, + author = {Starý Novotný, Vít and Enrico Gregorio and Max Chernoff and P. Spratte, Jonathan}, + title = {Convert control sequence with a variable number of undelimited parameters into a token list}, + url = {https://tex.stackexchange.com/q/716362/70941}, + urldate = {2024-04-28}, +} @book{tantau21, author = {Till Tantau and Joseph Wright and Vedran Miletić}, title = {The Beamer class}, @@ -827,6 +833,8 @@ abbr { \seq_map_inline:Nn \l_@@_header_identifiers_seq { \label { sec:##1 } } + \seq_clear:N + \l_@@_header_identifiers_seq }, }, } @@ -11342,7 +11350,7 @@ pdftex --shell-escape document.tex %### Typesetting Markdown {#tex-typesetting} % % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, -% \mdef{markdownInput}, and \mdef{markdownEscape} macros. +% \mdef{markinline}, \mdef{markdownInput}, and \mdef{markdownEscape} macros. % % The \mref{markdownBegin} macro marks the beginning of a markdown document % fragment and the \mref{markdownEnd} macro marks its end. @@ -11400,6 +11408,38 @@ pdftex --shell-escape document.tex % \bye % ``````` % +% You can use the \mref{markinline} macro to input inline markdown content. +% +% \end{markdown} +% \begin{macrocode} +\let\markinline\relax +% \end{macrocode} +% \par +% \begin{markdown} +% +% The following example plain \TeX{} code showcases the usage of the +% \mref{markinline} macro: +% +% ``` tex +% \input markdown +% \markinline{_Hello_ **world**} +% \bye +% ``````` +% +% The above code has the same effect as the below code: +% +% ``` tex +% \input markdown +% \markdownSetup{contentLevel=inline} +% \markdownBegin +% _Hello_ **world** ... +% \markdownEnd +% \bye +% ``````` +% +% The \mref{markinline} macro is subject to the same limitations as the +% \mref{markdownBegin} and \mref{markdownEnd} macros. +% % 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 @@ -11413,7 +11453,7 @@ pdftex --shell-escape document.tex % \par % \begin{markdown} % -% This macro is not subject to the abovelisted limitations of the +% This macro 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 @@ -11906,11 +11946,11 @@ macro after loading the package has no effect. % % The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent % sign (`\%`) at the beginning of a line will be discarded when buffering -% Markdown input (see Section <#sec:buffering>) or not. Notably, this -% enables the use of markdown when writing \TeX{} package documentation using -% the \pkg{Doc} \LaTeX{}~package~[@mittelbach17] or similar. The recognized -% values of the macro are `true` (discard) and `false` (retain). It defaults -% to `false`. +% Markdown input (see sections <#sec:buffering-block> and +% <#sec:buffering-inline>) or not. Notably, this enables the use of markdown +% when writing \TeX{} package documentation using the \pkg{Doc} +% \LaTeX{}~package~[@mittelbach17] or similar. The recognized values of the +% macro are `true` (discard) and `false` (retain). It defaults to `false`. % % \end{markdown} % \begin{macrocode} @@ -20158,6 +20198,8 @@ following text: } \tl_new:N \l_@@_renderer_definition_tl +\bool_new:N + \g_@@_appending_renderer_bool \cs_new:Nn \@@_define_renderer:nNn { \keys_define:nn @@ -20171,6 +20213,17 @@ following text: { \cP\#0 } { #1 } \l_@@_renderer_definition_tl + \bool_if:NT + \g_@@_appending_renderer_bool + { + \@@_tl_set_from_cs:NNn + \l_tmpa_tl + #2 + { #3 } + \tl_put_left:NV + \l_@@_renderer_definition_tl + \l_tmpa_tl + } \cs_generate_from_arg_count:NNnV #2 \cs_set:Npn @@ -20179,12 +20232,61 @@ following text: }, } } +% \end{macrocode} +% \par +% \begin{markdown} +% +% We define the function \mdef{@@_tl_set_from_cs:NNn} +% [@starynovotny24]. The function takes a token list, a control sequence with +% undelimited parameters, and the number of parameters the control sequence +% accepts, and locally assigns the replacement text of the control sequence +% to the token list. +% +% \end{markdown} +% \begin{macrocode} +\cs_new_protected:Nn + \@@_tl_set_from_cs:NNn + { + \tl_set:Nn + \l_tmpa_tl + { #2 } + \int_step_inline:nn + { #3 } + { + \exp_args:NNc + \tl_put_right:Nn + \l_tmpa_tl + { @@_tl_set_from_cs_parameter_ ##1 } + } + \exp_args:NNV + \tl_set:No + \l_tmpb_tl + \l_tmpa_tl + \regex_replace_all:nnN + { \cP. } + { \0\0 } + \l_tmpb_tl + \int_step_inline:nn + { #3 } + { + \regex_replace_all:nnN + { \c { @@_tl_set_from_cs_parameter_ ##1 } } + { \cP\# ##1 } + \l_tmpb_tl + } + \tl_set:NV + #1 + \l_tmpb_tl + } \cs_generate_variant:Nn \@@_define_renderer:nNn { ncV } \cs_generate_variant:Nn \cs_generate_from_arg_count:NNnn { NNnV } +\cs_generate_variant:Nn + \tl_put_left:Nn + { Nv } \keys_define:nn { markdown/options } { @@ -20194,7 +20296,6 @@ following text: { #1 } }, } -\ExplSyntaxOff % \end{macrocode} % \par % \begin{markdown} @@ -20211,13 +20312,92 @@ following text: % } % ``````` % -% In addition to exact token renderer names, we also support wildcards -% and enumerations that match multiple token renderer names: +% \end{markdown} +% \begin{macrocode} +\tl_new:N + \l_@@_renderer_glob_definition_tl +\seq_new:N + \l_@@_renderer_glob_results_seq +\regex_const:Nn + \c_@@_appending_key_regex + { \s*+$ } +\keys_define:nn + { markdown/options/renderers } + { + unknown .code:n = { +% \end{macrocode} +% \par +% \begin{markdown} +% +% Besides defining renderers at once, we can also define them incrementally +% using the appending operator (`+=`). This can be especially useful in +% defining rules for processing different \acro{HTML} class names and +% identifiers: +% ``` tex +% \markdownSetup{ +% renderers = { +% \% Start with empty renderers. +% headerAttributeContextBegin = {}, +% attributeClassName = {}, +% attributeIdentifier = {}, +% \% Define the processing of a single specific HTML class name. +% headerAttributeContextBegin += { +% \markdownSetup{ +% renderers = { +% attributeClassName += {...}, +% }, +% } +% }, +% \% Define the processing of a single specific HTML identifier. +% headerAttributeContextBegin += { +% \markdownSetup{ +% renderers = { +% attributeIdentifier += {...}, +% }, +% } +% }, +% }, +% } +% ``````` +% +% \end{markdown} +% \begin{macrocode} + \regex_match:NVTF + \c_@@_appending_key_regex + \l_keys_key_str + { + \bool_gset_true:N + \g_@@_appending_renderer_bool + \tl_set:NV + \l_tmpa_tl + \l_keys_key_str + \regex_replace_once:NnN + \c_@@_appending_key_regex + { } + \l_tmpa_tl + \tl_set:Nx + \l_tmpb_tl + { { \l_tmpa_tl } = } + \tl_put_right:Nn + \l_tmpb_tl + { { #1 } } + \keys_set:nV + { markdown/options/renderers } + \l_tmpb_tl + \bool_gset_false:N + \g_@@_appending_renderer_bool + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% In addition to exact token renderer names, we also support wildcards (`*`) +% and enumerations (`|`) that match multiple token renderer names: % ``` tex % \markdownSetup{ % renderers = { % heading* = {{\bf #1}}, \% Render headings using the bold face. -% jekyllData(String|Number) = { \% Render YAML string and numbers +% jekyllData(String|Number) = {\% \% Render YAML string and numbers % {\it #2}\% \% using italics. % }, % } @@ -20233,7 +20413,8 @@ following text: % } % ``````` % -% To determine the current token renderer, you can use the parameter `#0`: +% To determine the current token renderer, you can use the +% pseudo-parameter `#0`: % ``` tex % \markdownSetup{ % renderers = { @@ -20244,7 +20425,59 @@ following text: % % \end{markdown} % \begin{macrocode} -\ExplSyntaxOn + { + \@@_glob_seq:VnN + \l_keys_key_str + { g_@@_renderers_seq } + \l_@@_renderer_glob_results_seq + \seq_if_empty:NTF + \l_@@_renderer_glob_results_seq + { + \msg_error:nnV + { markdown } + { undefined-renderer } + \l_keys_key_str + } + { + \tl_set:Nn + \l_@@_renderer_glob_definition_tl + { \exp_not:n { #1 } } + \seq_map_inline:Nn + \l_@@_renderer_glob_results_seq + { + \tl_set:Nn + \l_tmpa_tl + { { ##1 } = } + \tl_put_right:Nx + \l_tmpa_tl + { { \l_@@_renderer_glob_definition_tl } } + \keys_set:nV + { markdown/options/renderers } + \l_tmpa_tl + } + } + } + }, + } +\msg_new:nnn + { markdown } + { undefined-renderer } + { + Renderer~#1~is~undefined. + } +\cs_generate_variant:Nn + \@@_glob_seq:nnN + { VnN } +\cs_generate_variant:Nn + \cs_generate_from_arg_count:NNnn + { cNVV } +\cs_generate_variant:Nn + \msg_error:nnn + { nnV } +\prg_generate_conditional_variant:Nnn + \regex_match:Nn + { NV } + { TF } \prop_new:N \g_@@_glob_cache_prop \tl_new:N @@ -20306,72 +20539,6 @@ following text: \cs_generate_variant:Nn \prop_gput:Nnn { NeV } -\seq_new:N - \l_@@_renderer_glob_results_seq -\keys_define:nn - { markdown/options/renderers } - { - unknown .code:n = { - \@@_glob_seq:VnN - \l_keys_key_str - { g_@@_renderers_seq } - \l_@@_renderer_glob_results_seq - \seq_if_empty:NTF - \l_@@_renderer_glob_results_seq - { - \msg_error:nnV - { markdown } - { undefined-renderer } - \l_keys_key_str - } - { - \tl_set:Nn - \l_@@_renderer_definition_tl - { #1 } - \seq_map_inline:Nn - \l_@@_renderer_glob_results_seq - { - \@@_renderer_tl_to_csname:nN - { ##1 } - \l_tmpa_tl - \prop_get:NnN - \g_@@_renderer_arities_prop - { ##1 } - \l_tmpb_tl - \int_set:Nn - \l_tmpa_int - \l_tmpb_tl - \tl_set:NV - \l_tmpb_tl - \l_@@_renderer_definition_tl - \regex_replace_all:nnN - { \cP\#0 } - { ##1 } - \l_tmpb_tl - \cs_generate_from_arg_count:cNVV - { \l_tmpa_tl } - \cs_set:Npn - \l_tmpa_int - \l_tmpb_tl - } - } - }, - } -\msg_new:nnn - { markdown } - { undefined-renderer } - { - Renderer~#1~is~undefined. - } -\cs_generate_variant:Nn - \@@_glob_seq:nnN - { VnN } -\cs_generate_variant:Nn - \cs_generate_from_arg_count:NNnn - { cNVV } -\cs_generate_variant:Nn - \msg_error:nnn - { nnV } % \end{macrocode} % \begin{markdown} % @@ -20750,6 +20917,8 @@ following text: } \tl_new:N \l_@@_renderer_prototype_definition_tl +\bool_new:N + \g_@@_appending_renderer_prototype_bool \cs_new:Nn \@@_define_renderer_prototype:nNn { \keys_define:nn @@ -20763,6 +20932,17 @@ following text: { \cP\#0 } { #1 } \l_@@_renderer_prototype_definition_tl + \bool_if:NT + \g_@@_appending_renderer_prototype_bool + { + \@@_tl_set_from_cs:NNn + \l_tmpa_tl + #2 + { #3 } + \tl_put_left:NV + \l_@@_renderer_prototype_definition_tl + \l_tmpa_tl + } \cs_generate_from_arg_count:NNnV #2 \cs_set:Npn @@ -20791,7 +20971,6 @@ following text: \cs_generate_variant:Nn \@@_define_renderer_prototype:nNn { ncV } -\ExplSyntaxOff % \end{macrocode} % \par % \begin{markdown} @@ -20808,8 +20987,81 @@ following text: % } % ``````` % -% In addition to exact token renderer names, we also support wildcards -% and enumerations that match multiple token renderer prototype names: +% \end{markdown} +% \begin{macrocode} +\keys_define:nn + { markdown/options/renderer-prototypes } + { + unknown .code:n = { +% \end{macrocode} +% \par +% \begin{markdown} +% +% Besides defining renderer prototypes at once, we can also define them +% incrementally using the appending operator (`+=`). This can be especially +% useful in defining rules for processing different \acro{HTML} class names +% and identifiers: +% ``` tex +% \markdownSetup{ +% rendererPrototypes = { +% \% Start with empty renderer prototypes. +% headerAttributeContextBegin = {}, +% attributeClassName = {}, +% attributeIdentifier = {}, +% \% Define the processing of a single specific HTML class name. +% headerAttributeContextBegin += { +% \markdownSetup{ +% rendererPrototypes = { +% attributeClassName += {...}, +% }, +% } +% }, +% \% Define the processing of a single specific HTML identifier. +% headerAttributeContextBegin += { +% \markdownSetup{ +% rendererPrototypes = { +% attributeIdentifier += {...}, +% }, +% } +% }, +% }, +% } +% ``````` +% +% \end{markdown} +% \begin{macrocode} + \regex_match:NVTF + \c_@@_appending_key_regex + \l_keys_key_str + { + \bool_gset_true:N + \g_@@_appending_renderer_prototype_bool + \tl_set:NV + \l_tmpa_tl + \l_keys_key_str + \regex_replace_once:NnN + \c_@@_appending_key_regex + { } + \l_tmpa_tl + \tl_set:Nx + \l_tmpb_tl + { { \l_tmpa_tl } = } + \tl_put_right:Nn + \l_tmpb_tl + { { #1 } } + \keys_set:nV + { markdown/options/renderer-prototypes } + \l_tmpb_tl + \bool_gset_false:N + \g_@@_appending_renderer_prototype_bool + } +% \end{macrocode} +% \par +% \begin{markdown} +% +% In addition to exact token renderer prototype names, we also support +% wildcards (`*`) and enumerations (`|`) that match multiple token renderer +% prototype names: % ``` tex % \markdownSetup{ % rendererPrototypes = { @@ -20831,7 +21083,7 @@ following text: % ``````` % % To determine the current token renderer prototype, you can use the -% parameter `#0`: +% pseudo-parameter `#0`: % ``` tex % \markdownSetup{ % rendererPrototypes = { @@ -20842,54 +21094,36 @@ following text: % % \end{markdown} % \begin{macrocode} -\ExplSyntaxOn -\seq_new:N - \l_@@_renderer_prototype_glob_results_seq -\keys_define:nn - { markdown/options/renderer-prototypes } - { - unknown .code:n = { - \@@_glob_seq:VnN - \l_keys_key_str - { g_@@_renderers_seq } - \l_@@_renderer_prototype_glob_results_seq - \seq_if_empty:NTF - \l_@@_renderer_prototype_glob_results_seq { - \msg_error:nnV - { markdown } - { undefined-renderer-prototype } + \@@_glob_seq:VnN \l_keys_key_str - } - { - \tl_set:Nn - \l_@@_renderer_prototype_definition_tl - { #1 } - \seq_map_inline:Nn - \l_@@_renderer_prototype_glob_results_seq + { g_@@_renderers_seq } + \l_@@_renderer_glob_results_seq + \seq_if_empty:NTF + \l_@@_renderer_glob_results_seq { - \@@_renderer_prototype_tl_to_csname:nN - { ##1 } - \l_tmpa_tl - \prop_get:NnN - \g_@@_renderer_arities_prop - { ##1 } - \l_tmpb_tl - \int_set:Nn - \l_tmpa_int - \l_tmpb_tl - \tl_set:NV - \l_tmpb_tl - \l_@@_renderer_prototype_definition_tl - \regex_replace_all:nnN - { \cP\#0 } - { ##1 } - \l_tmpb_tl - \cs_generate_from_arg_count:cNVV - { \l_tmpa_tl } - \cs_set:Npn - \l_tmpa_int - \l_tmpb_tl + \msg_error:nnV + { markdown } + { undefined-renderer-prototype } + \l_keys_key_str + } + { + \tl_set:Nn + \l_@@_renderer_glob_definition_tl + { \exp_not:n { #1 } } + \seq_map_inline:Nn + \l_@@_renderer_glob_results_seq + { + \tl_set:Nn + \l_tmpa_tl + { { ##1 } = } + \tl_put_right:Nx + \l_tmpa_tl + { { \l_@@_renderer_glob_definition_tl } } + \keys_set:nV + { markdown/options/renderer-prototypes } + \l_tmpa_tl + } } } }, @@ -21128,7 +21362,8 @@ pdflatex --shell-escape document.tex % %### Typesetting Markdown % The interface exposes the \envmdef{markdown} and \envmdef{markdown*} -% \LaTeX{} environments, and redefines the \mref{markdownInput} command. +% \LaTeX{} environments, and redefines the \mref{markinline} and +% \mref{markdownInput} commands. % % The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are used % to typeset markdown document fragments. Both \LaTeX{} environments accept @@ -21169,6 +21404,13 @@ pdflatex --shell-escape document.tex % \end{document} \end{document} % ``````` % +% 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. +% % 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 @@ -25155,7 +25397,7 @@ function M.writer.new(options) function self.blockquote(s) if not self.is_writing then return "" end return {"\\markdownRendererBlockQuoteBegin\n",s, - "\n\\markdownRendererBlockQuoteEnd "} + "\\markdownRendererBlockQuoteEnd "} end % \end{macrocode} % \par @@ -25645,7 +25887,7 @@ function M.writer.new(options) end if self.is_writing and #normalized_attributes > 0 then - table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd ") + table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd{}") end return buf @@ -30663,7 +30905,7 @@ M.extensions.fenced_code = function(blank_before_code_fence, table.insert(buf, {"\\markdownRendererInputFencedCode{", name,"}{",self.string(i),"}{",self.infostring(i),"}"}) if attr ~= nil then - table.insert(buf, "\\markdownRendererFencedCodeAttributeContextEnd") + table.insert(buf, "\\markdownRendererFencedCodeAttributeContextEnd{}") end return buf end @@ -30884,7 +31126,7 @@ M.extensions.fenced_divs = function(blank_before_div_fence) function self.div_begin(attributes) local start_output = {"\\markdownRendererFencedDivAttributeContextBegin\n", self.attributes(attributes)} - local end_output = {"\\markdownRendererFencedDivAttributeContextEnd "} + local end_output = {"\\markdownRendererFencedDivAttributeContextEnd{}"} return self.push_attributes("div", attributes, start_output, end_output) end % \end{macrocode} @@ -33453,7 +33695,7 @@ end % \par % \begin{markdown} % -%### Buffering Markdown Input {#buffering} +%### Buffering Block-Level Markdown Input {#buffering-block} % % The macros \mdef{markdownInputFileStream} and \mdef{markdownOutputFileStream} % contain the number of the input and output file streams that will be used for @@ -33512,7 +33754,8 @@ end |markdownIfOption{frozenCache}{}{@ |immediate|openout|markdownOutputFileStream@ |markdownOptionInputTempFileName|relax@ - |markdownInfo{Buffering markdown input into the temporary @ + |markdownInfo{@ + Buffering block-level markdown input into the temporary @ input file "|markdownOptionInputTempFileName" and scanning @ for the closing token sequence "#1"}@ }@ @@ -33694,6 +33937,125 @@ end % \end{macrocode} % \begin{markdown} % +%### Buffering Inline Markdown Input {#buffering-inline} +% +% This section describes the implementation of the macro \mref{markinline}. +% +% \end{markdown} +% \begin{macrocode} +\ExplSyntaxOn +\tl_new:N + \g_@@_after_markinline_tl +\tl_gset:Nn + \g_@@_after_markinline_tl + { \unskip } +\cs_new:Npn + \markinline + { +% \end{macrocode} +% \begin{markdown} +% +% Locally change the category of the special plain \TeX{} characters +% to *other* in order to prevent unwanted interpretation of the input +% markdown text as \TeX{} code. +% +% \end{markdown} +% \begin{macrocode} + \group_begin: + \cctab_select:N + \c_other_cctab +% \end{macrocode} +% \begin{markdown} +% +% Unless we are reading markdown documents from the frozen cache, +% open the file \Opt{inputTempFileName} for writing. +% +% \end{markdown} +% \begin{macrocode} + \@@_if_option:nF + { frozenCache } + { + \immediate + \openout + \markdownOutputFileStream + \markdownOptionInputTempFileName + \relax + \msg_info:nne + { markdown } + { buffering-markinline } + { \markdownOptionInputTempFileName } + } +% \end{macrocode} +% \begin{markdown} +% +% Peek ahead and extract the inline markdown text. +% +% \end{markdown} +% \begin{macrocode} + \peek_regex_replace_once:nnF + { { (.*?) } } + { +% \end{macrocode} +% \begin{markdown} +% +% Unless we are reading markdown documents from the frozen cache, +% store the text in the file \Opt{inputTempFileName} and close it. +% +% \end{markdown} +% \begin{macrocode} + \c { @@_if_option:nF } + \cB { frozenCache \cE } + \cB { + \c { immediate } + \c { write } + \c { markdownOutputFileStream } + \cB { \1 \cE } + \c { immediate } + \c { closeout } + \c { markdownOutputFileStream } + \cE } +% \end{macrocode} +% \begin{markdown} +% +% Reset the category codes and `\input` the result of the conversion. +% +% \end{markdown} +% \begin{macrocode} + \c { group_end: } + \c { group_begin: } + \c { @@_setup:n } + \cB { contentLevel = inline \cE } + \c { markdownInput } + \cB { + \c { markdownOptionOutputDir } / + \c { markdownOptionInputTempFileName } + \cE } + \c { group_end: } + \c { tl_use:N } + \c { g_@@_after_markinline_tl } + } + { + \msg_error:nn + { markdown } + { markinline-peek-failure } + \group_end: + \tl_use:N + \g_@@_after_markinline_tl + } + } +\msg_new:nnn + { markdown } + { buffering-markinline } + { Buffering~inline~markdown~input~into~the~temporary~input~file~"#1". } +\msg_new:nnnn + { markdown } + { markinline-peek-failure } + { Use~of~\iow_char:N \\ markinline~doesn't~match~its~definition } + { The~macro~should~be~followed~by~inline~markdown~text~in~curly~braces } +\ExplSyntaxOff +% \end{macrocode} +% \begin{markdown} +% %### Typesetting Markdown % % The \mref{markdownInput} macro uses an implementation of the @@ -33821,21 +34183,49 @@ end % \par % \begin{markdown} % -%### Logging Facilities -% The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section <#sec:tex-interface-logging>) to use the \LaTeX{} `\PackageInfo`, -% `\PackageWarning`, and `\PackageError` macros. +%### Typesetting Markdown +% The \mdef{markinlinePlainTeX} macro is used to store the original plain +% \TeX{} implementation of the \mref{markinline} macro. The \mref{markinline} +% macro is then redefined to accept an optional argument with options +% recognized by the \LaTeX{} interface (see Section <#sec:latex-options>). % % \end{markdown} % \begin{macrocode} +\ExplSyntaxOn +\cs_gset_eq:NN + \markinlinePlainTeX + \markinline +\cs_gset:Npn + \markinline + { + \peek_regex_replace_once:nn + { ( \[ (.*?) \] ) ? } + { +% \end{macrocode} +% \par +% \begin{markdown} +% +% Apply the options locally. +% +% \end{markdown} +% \begin{macrocode} + \c { group_begin: } + \c { @@_setup:n } + \cB { \2 \cE } + \c { tl_put_right:Nn } + \c { g_@@_after_markinline_tl } + \cB { \c { group_end: } \cE } + \c { markinlinePlainTeX } + } + } +\ExplSyntaxOff % \end{macrocode} % \par % \begin{markdown} % -%### Typesetting Markdown % The \mdef{markdownInputPlainTeX} macro is used to store the original plain % \TeX{} implementation of the \mref{markdownInput} macro. The \mref{markdownInput} -% is then redefined to accept an optional argument with options recognized by +% macro is then redefined to accept an optional argument with options recognized by % the \LaTeX{} interface (see Section <#sec:latex-options>). % % \end{markdown} @@ -34718,35 +35108,86 @@ end % \par % \begin{markdown} % -% If identifier attributes appear at the beginning of a section, we make them -% produce the `\label` macro. +% If \acro{HTML} identifiers appear after a heading, we make them +% produce `\label` macros. % % \end{markdown} % \begin{macrocode} \ExplSyntaxOn -\seq_new:N \l_@@_header_identifiers_seq -\markdownSetup{ - rendererPrototypes = { - headerAttributeContextBegin = { - \seq_clear:N \l_@@_header_identifiers_seq - \markdownSetup - { - renderers = { - attributeIdentifier = { - \seq_put_right:Nn - \l_@@_header_identifiers_seq - { ##1 } +\seq_new:N + \l_@@_header_identifiers_seq +\markdownSetup + { + rendererPrototypes = { + headerAttributeContextBegin = { + \markdownSetup + { + rendererPrototypes = { + attributeIdentifier = { + \seq_put_right:Nn + \l_@@_header_identifiers_seq + { ##1 } + }, }, - }, - } + } + }, + headerAttributeContextEnd = { + \seq_map_inline:Nn + \l_@@_header_identifiers_seq + { \label { ##1 } } + \seq_clear:N + \l_@@_header_identifiers_seq + }, }, - headerAttributeContextEnd = { - \seq_map_inline:Nn - \l_@@_header_identifiers_seq - { \label { ##1 } } + } +% \end{macrocode} +% \begin{markdown} +% +% If the `unnumbered` \acro{HTML} class (or the `{-}` shorthand) appears after +% a heading the heading and all its subheadings will be unnumbered. +% +% \end{markdown} +% \begin{macrocode} +\bool_new:N + \l_@@_header_unnumbered_bool +\markdownSetup + { + rendererPrototypes = { + headerAttributeContextBegin += { + \markdownSetup + { + rendererPrototypes = { + attributeClassName = { + \bool_if:nT + { + \str_if_eq_p:nn + { ##1 } + { unnumbered } && + ! \l_@@_header_unnumbered_bool + } + { + \group_begin: + \bool_set_true:N + \l_@@_header_unnumbered_bool + \c@secnumdepth = 0 + \markdownSetup + { + rendererPrototypes = { + sectionBegin = { + \group_begin: + }, + sectionEnd = { + \group_end: + }, + }, + } + } + }, + }, + } + }, }, - }, -} + } \ExplSyntaxOff \markdownSetup{rendererPrototypes={ superscript = {\textsuperscript{#1}}, diff --git a/macros/generic/markdown/markdown.html b/macros/generic/markdown/markdown.html index 277f98bdeb..65f1de7d51 100644 --- a/macros/generic/markdown/markdown.html +++ b/macros/generic/markdown/markdown.html @@ -93,7 +93,7 @@ <header id="title-block-header"> <h1 class="title">Markdown Package User Manual</h1> <p class="author">Vít Starý Novotný</p> -<p class="date">3.4.3-0-ge2c6be1a 2024-04-04</p> +<p class="date">3.5.0-0-gfd01a252 2024-04-29</p> </header> <nav id="TOC" role="doc-toc"> <ul> diff --git a/macros/generic/markdown/markdown.pdf b/macros/generic/markdown/markdown.pdf Binary files differindex 8e42e32d0b..a4e313f081 100644 --- a/macros/generic/markdown/markdown.pdf +++ b/macros/generic/markdown/markdown.pdf |