diff options
author | Karl Berry <karl@freefriends.org> | 2022-12-23 21:03:50 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-12-23 21:03:50 +0000 |
commit | 8d383d484835575910b71ef5e1746d57be9afef3 (patch) | |
tree | 5d61e2067af838ba094af5faed2682ca07373ff1 /Master/texmf-dist/source | |
parent | 23f484c87d10a1d39e2ea85bab67f04e17adff4a (diff) |
markdown (23dec22)
git-svn-id: svn://tug.org/texlive/trunk@65339 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 8421 |
1 files changed, 4559 insertions, 3862 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx index b1659244769..5b3f73cb8e2 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.dtx +++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx @@ -1,6 +1,6 @@ % \iffalse %<*driver> -\documentclass[nohyperref]{ltxdockit} +\documentclass{ltxdockit} \usepackage[american]{babel} \usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted} @@ -1145,11 +1145,11 @@ local md5 = require("md5") % %: A library that provides access to the filesystem via \acro{os}-specific % syscalls. It is used by the plain \TeX{} code to create the cache -% directory specified by the \mref{markdownOptionCacheDir} macro before -% interfacing with the \pkg{Lunamark} library. \pkg{Lua File System} is -% included in all releases of Lua\TeX{} (\TeX Live${}\geq{}2008$). +% directory specified by the \Opt{cacheDir} option before interfacing with +% the \pkg{Lunamark} library. \pkg{Lua File System} is included in all +% releases of Lua\TeX{} (\TeX Live${}\geq{}2008$). % -% The plain \TeX{} code makes use of the \luamref{isdir} method that was added +% The plain \TeX{} code makes use of the `isdir` method that was added % to the \pkg{Lua File System} library by the Lua\TeX{} engine % developers~[@luatex21, Section 4.2.4]. % @@ -1159,7 +1159,7 @@ local md5 = require("md5") % Unless you convert markdown documents to \TeX{} manually using the Lua % command-line interface (see Section <#sec:lua-cli-interface>), the plain % \TeX{} part of the package will require that either the Lua\TeX{} -% \mref{directlua} primitive or the shell access file stream 18 is available in +% `\directlua` primitive or the shell access file stream 18 is available in % your \TeX{} engine. If only the shell access file stream is available in your % \TeX{} engine (as is the case with \hologo{pdfTeX} and \Hologo{XeTeX}) or if % you enforce the use of shell using the \mref{markdownMode} macro, then unless @@ -1202,18 +1202,17 @@ local md5 = require("md5") % % \pkg{url} % -%: A package that provides the \mref{url} macro for the typesetting of -% links. +%: A package that provides the `\url` macro for the typesetting of links. % % \pkg{graphicx} % -%: A package that provides the \mref{includegraphics} macro for the typesetting +%: A package that provides the `\includegraphics` macro for the typesetting % of images. % % \pkg{paralist} % -%: A package that provides the \envmref{compactitem}, \envmref{compactenum}, and -% \envmref{compactdesc} macros for the typesetting of tight bulleted lists, +%: A package that provides the `compactitem`, `compactenum`, and +% `compactdesc` macros for the typesetting of tight bulleted lists, % ordered lists, and definition lists. % % \pkg{ifthen} @@ -1224,18 +1223,18 @@ local md5 = require("md5") % % \pkg{fancyvrb} % -%: A package that provides the \mref{VerbatimInput} macros for the verbatim +%: A package that provides the `\VerbatimInput` macros for the verbatim % inclusion of files containing code. % % \pkg{csvsimple} % -%: A package that provides the \mref{csvautotabular} macro for typesetting +%: A package that provides the `\csvautotabular` macro for typesetting % \acro{csv} files in the default renderer prototypes for iA\,Writer % content blocks. % % \pkg{gobble} % -%: A package that provides the \mref{\@gobblethree} \TeX{} command that +%: A package that provides the `\@gobblethree` \TeX{} command that % is used in the default renderer prototype for citations. The package % is included in \TeX Live${}\geq{}2016$. % @@ -1680,7 +1679,7 @@ local walkable_syntax = { % \luamref{reader->insert_pattern} with `"Inline after Emph"` (or `"Inline % before Link"`) and `pattern` as the arguments. % -% The \luamdef{reader->add_special_character} method adds a new character with +% The \luamref{reader->add_special_character} method adds a new character with % special meaning to the grammar of markdown. The method receives the character % as its only argument. % @@ -2569,7 +2568,7 @@ defaultOptions.debugExtensionsFileName = "debug-extensions.json" The frozen cache makes it possible to later typeset a plain \TeX{} document that contains markdown documents without invoking Lua using - the \mref{markdownOptionFrozenCache} plain \TeX{} option. As a result, the + the \Opt{frozenCache} plain \TeX{} option. As a result, the plain \TeX{} document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. @@ -3048,7 +3047,7 @@ following content: convert = markdown.new({fencedCode = true}) input = "A paragraph." .. newline .. "```" .. newline .. - "A code fence." .. newline .. + "A fenced code." .. newline .. "```" .. newline tex.sprint(convert(input)) @@ -3056,7 +3055,7 @@ following content: fencedCode = true, blankBeforeCodeFence = true}) input = "A paragraph." .. newline .. "```" .. newline .. - "Not a code fence." .. newline .. + "Not a fenced code." .. newline .. "```" .. newline tex.sprint(convert(input)) } \bye @@ -3071,10 +3070,10 @@ following text: > A paragraph. > > ``` -> A code fence. +> A fenced code. > ``` > -> A paragraph. ``` Not a code fence. ``` +> A paragraph. ``` Not a fenced code. ``` ##### Lua CLI Example {.unnumbered} @@ -3129,7 +3128,7 @@ following content: \markdownBegin A paragraph. ``` -A code fence. +A fenced code. ``` \markdownEnd @@ -3137,7 +3136,7 @@ A code fence. \markdownBegin A paragraph. ``` -Not a code fence. +Not a fenced code. ``` \markdownEnd @@ -3153,10 +3152,10 @@ following text: > A paragraph. > > ``` -> A code fence. +> A fenced code. > ``` > -> A paragraph. ``` Not a code fence. ``` +> A paragraph. ``` Not a fenced code. ``` ##### \LaTeX{} Example {.unnumbered} @@ -3170,14 +3169,14 @@ following content: \begin{markdown} A paragraph. ``` -A code fence. +A fenced code. ``` \end{markdown} \begin{markdown*}{blankBeforeCodeFence} A paragraph. ``` -Not a code fence. +Not a fenced code. ``` \end{markdown*} @@ -3193,10 +3192,10 @@ following text: > A paragraph. > > ``` -> A code fence. +> A fenced code. > ``` > -> A paragraph. ``` Not a code fence. ``` +> A paragraph. ``` Not a fenced code. ``` ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -3210,7 +3209,7 @@ following content: \startmarkdown A paragraph. ``` -A code fence. +A fenced code. ``` \stopmarkdown @@ -3218,7 +3217,7 @@ A code fence. \startmarkdown A paragraph. ``` -Not a code fence. +Not a fenced code. ``` \stopmarkdown @@ -3234,10 +3233,10 @@ following text: > A paragraph. > > ``` -> A code fence. +> A fenced code. > ``` > -> A paragraph. ``` Not a code fence. ``` +> A paragraph. ``` Not a fenced code. ``` %</manual-options> %<*tex> @@ -3260,6 +3259,85 @@ defaultOptions.blankBeforeCodeFence = false %</lua,lua-cli> %<*manual-options> +#### Option `blankBeforeDivFence` + +`blankBeforeDivFence` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{blankBeforeDivFence}{\opt{true}, \opt{false}} +% +: true + + : Require a blank line before the closing fence of a fenced div. + + false + + : Do not require a blank line before the closing fence of a fenced div. + +% \end{markdown} +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\documentclass{article} +\usepackage[fencedDivs]{markdown} +\begin{document} + +\begin{markdown} +A paragraph. +::: {.identifier} +A fenced div. +::: +\end{markdown} + +\begin{markdown*}{blankBeforeDivFence} +A paragraph. +``` +Not a fenced div. +``` +\end{markdown*} + +\end{document} +```````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> A fenced div. +> +> A paragraph. ::: {.identifier} Not a fenced div. ::: + +%</manual-options> +%<*tex> +% \fi +% \begin{macrocode} +\@@_add_lua_option:nnn + { blankBeforeDivFence } + { boolean } + { false } +% \end{macrocode} +% \iffalse +%</tex> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.blankBeforeDivFence = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `blankBeforeHeading` `blankBeforeHeading` (default value: `false`) @@ -3492,6 +3570,100 @@ defaultOptions.blankBeforeHeading = false %</lua,lua-cli> %<*manual-options> +#### Option `bracketedSpans` + +`bracketedSpans` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{bracketedSpans}{\opt{true}, \opt{false}} +% +: true + + : Enable the Pandoc bracketed spans extension: + + ``` md + [This is *some text*]{.class key="val"} + `````` + +: false + + : Disable the Pandoc bracketed spans extension: + +% \end{markdown} +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\documentclass{article} +\usepackage[bracketedSpans]{markdown} +\usepackage{expl3} +\ExplSyntaxOn +\markdownSetup{ + renderers = { + bracketedSpanAttributeContextBegin = { + \group_begin: + \color_group_begin: + \markdownSetup{ + renderers = { + attributeKeyValue = { + \str_if_eq:nnT + { #1 } + { color } + { + \color_select:n { #2 } + } + }, + }, + } + }, + bracketedSpanAttributeContextEnd = { + \color_group_end: + \group_end: + }, + }, +} +\ExplSyntaxOff +\begin{document} +\begin{markdown} +Here is some [colored text]{color=red}. +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex --shell-escape document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Here is some [colored text]{color=red}. + +%</manual-options> +%<*tex> +% \fi +% \begin{macrocode} +\@@_add_lua_option:nnn + { bracketedSpans } + { boolean } + { false } +% \end{macrocode} +% \iffalse +%</tex> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.bracketedSpans = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `breakableBlockquotes` `breakableBlockquotes` (default value: `false`) @@ -4694,6 +4866,130 @@ defaultOptions.eagerCache = true %</lua,lua-cli> %<*manual-options> +#### Option `expectJekyllData` + +`expectJekyllData` (default value: `false`) + +% \fi +% \markdownBegin +% +% \Optitem[false]{expectJekyllData}{\opt{true}, \opt{false}} +% +: false + + : When the \Opt{jekyllData} option is enabled, then a markdown document + may begin with \acro{yaml} metadata if and only if the metadata begin + with the end-of-directives marker (`---`) and they end with either the + end-of-directives or the end-of-document marker (`...`): + + ~~~~~ latex + \documentclass{article} + \usepackage[jekyllData]{markdown} + \begin{document} + \begin{markdown} + --- + - this + - is + - YAML + ... + - followed + - by + - Markdown + \end{markdown} + \begin{markdown} + - this + - is + - Markdown + \end{markdown} + \end{document} + ~~~~~~~~~~~ + +: true + + : When the \Opt{jekyllData} option is enabled, then a markdown document may + begin directly with \acro{yaml} metadata and may contain nothing but + \acro{yaml} metadata. + + ~~~~~ latex + \documentclass{article} + \usepackage[jekyllData, expectJekyllData]{markdown} + \begin{document} + \begin{markdown} + - this + - is + - YAML + ... + - followed + - by + - Markdown + \end{markdown} + \begin{markdown} + - this + - is + - YAML + \end{markdown} + \end{document} + ~~~~~~~~~~~ + +% \markdownEnd +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `jane-doe.yml` with the +following content: +``` yaml +name: Jane Doe +age: 99 +``` +Using a text editor, create also a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[jekyllData]{markdown} +\markdownSetup{ + jekyllDataRenderers = { + name = {\gdef\name{#1}}, + code = {\gdef\age{#1}}, + }, + renderers = { + jekyllDataEnd = {\name{} is \age{} years old.}, + } +} +\begin{document} +\markdownInput[expectJekyllData]{jane-doe.yml} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +%</manual-options> +%<*tex> +% \fi +% \begin{macrocode} +\@@_add_lua_option:nnn + { expectJekyllData } + { boolean } + { false } +% \end{macrocode} +% \iffalse +%</tex> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.expectJekyllData = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `extensions` `extensions` (default value: `{}`) @@ -4845,130 +5141,6 @@ defaultOptions.extensions = {} %</lua,lua-cli> %<*manual-options> -#### Option `expectJekyllData` - -`expectJekyllData` (default value: `false`) - -% \fi -% \markdownBegin -% -% \Optitem[false]{expectJekyllData}{\opt{true}, \opt{false}} -% -: false - - : When the \Opt{jekyllData} option is enabled, then a markdown document - may begin with \acro{yaml} metadata if and only if the metadata begin - with the end-of-directives marker (`---`) and they end with either the - end-of-directives or the end-of-document marker (`...`): - - ~~~~~ latex - \documentclass{article} - \usepackage[jekyllData]{markdown} - \begin{document} - \begin{markdown} - --- - - this - - is - - YAML - ... - - followed - - by - - Markdown - \end{markdown} - \begin{markdown} - - this - - is - - Markdown - \end{markdown} - \end{document} - ~~~~~~~~~~~ - -: true - - : When the \Opt{jekyllData} option is enabled, then a markdown document may - begin directly with \acro{yaml} metadata and may contain nothing but - \acro{yaml} metadata. - - ~~~~~ latex - \documentclass{article} - \usepackage[jekyllData, expectJekyllData]{markdown} - \begin{document} - \begin{markdown} - - this - - is - - YAML - ... - - followed - - by - - Markdown - \end{markdown} - \begin{markdown} - - this - - is - - YAML - \end{markdown} - \end{document} - ~~~~~~~~~~~ - -% \markdownEnd -% \iffalse - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `jane-doe.yml` with the -following content: -``` yaml -name: Jane Doe -age: 99 -``` -Using a text editor, create also a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[jekyllData]{markdown} -\markdownSetup{ - jekyllDataRenderers = { - name = {\gdef\name{#1}}, - code = {\gdef\age{#1}}, - }, - renderers = { - jekyllDataEnd = {\name{} is \age{} years old.}, - } -} -\begin{document} -\markdownInput[expectJekyllData]{jane-doe.yml} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Jane Doe is 99 years old. - -%</manual-options> -%<*tex> -% \fi -% \begin{macrocode} -\@@_add_lua_option:nnn - { expectJekyllData } - { boolean } - { false } -% \end{macrocode} -% \iffalse -%</tex> -%<*lua,lua-cli> -% \fi -% \begin{macrocode} -defaultOptions.expectJekyllData = false -% \end{macrocode} -% \par -% \iffalse -%</lua,lua-cli> -%<*manual-options> - #### Option `fancyLists` `fancyLists` (default value: `false`) @@ -5237,6 +5409,83 @@ defaultOptions.fencedCode = false %</lua,lua-cli> %<*manual-options> +#### Option `fencedDivs` + +`fencedDivs` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{fencedDivs}{\opt{true}, \opt{false}} +% +: true + + : Enable the Pandoc fenced divs extension: + + ``` md + ::::: {#special .sidebar} + Here is a paragraph. + + And another. + ::::: + `````` + +: false + + : Disable the Pandoc fenced divs extension: + +% \end{markdown} +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\documentclass{article} +\usepackage[fencedDivs]{markdown} +\begin{document} +\begin{markdown}{slice=special} +Here is a regular paragraph. + +::::: {#special} +Here is a special paragraph. +::::: + +And here is another regular paragraph. +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex --shell-escape document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Here is a special paragraph. + +%</manual-options> +%<*tex> +% \fi +% \begin{macrocode} +\@@_add_lua_option:nnn + { fencedDivs } + { boolean } + { false } +% \end{macrocode} +% \iffalse +%</tex> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.fencedDivs = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `finalizeCache` `finalizeCache` (default value: `false`) @@ -5252,7 +5501,7 @@ defaultOptions.fencedCode = false The frozen cache makes it possible to later typeset a plain \TeX{} document that contains markdown documents without invoking Lua using - the \mref{markdownOptionFrozenCache} plain \TeX{} option. As a result, the + the \Opt{frozenCache} plain \TeX{} option. As a result, the plain \TeX{} document becomes more portable, but further changes in the order and the content of markdown documents will not be reflected. @@ -5401,186 +5650,6 @@ defaultOptions.finalizeCache = false %</lua,lua-cli> %<*manual-options> -#### Option `notes` - -`notes` (default value: `false`) - -% \fi -% \begin{markdown} -% -% \Optitem[false]{notes}{\opt{true}, \opt{false}} -% -: true - - : Enable the Pandoc note syntax extension: - - ``` md - Here is a note reference,[^1] and another.[^longnote] - - [^1]: Here is the note. - - [^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they - belong to the previous note. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph notes - work like multi-paragraph list items. - - This paragraph won't be part of the note, because it - isn't indented. - `````` - -: false - - : Disable the Pandoc note syntax extension. - -% \end{markdown} -% \iffalse - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[notes]{markdown} -\begin{document} -\begin{markdown} -Here is a note reference,[^1] and another.[^longnote] - -[^1]: Here is the note. - -[^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they -belong to the previous note. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph notes - work like multi-paragraph list items. - -This paragraph won't be part of the note, because it -isn't indented. -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Here is a note reference,[^1] and another.[^longnote] -> -> [^1]: Here is the note. -> -> [^longnote]: Here's one with multiple blocks. -> -> Subsequent paragraphs are indented to show that they -> belong to the previous note. -> -> { some.code } -> -> The whole paragraph can be indented, or just the -> first line. In this way, multi-paragraph notes -> work like multi-paragraph list items. -> -> This paragraph won't be part of the note, because it -> isn't indented. - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\setupmarkdown[notes = yes] -\starttext -\startmarkdown -Here is a note reference,[^1] and another.[^longnote] - -[^1]: Here is the note. - -[^longnote]: Here's one with multiple blocks. - - Subsequent paragraphs are indented to show that they -belong to the previous note. - - { some.code } - - The whole paragraph can be indented, or just the - first line. In this way, multi-paragraph notes - work like multi-paragraph list items. - -This paragraph won't be part of the note, because it -isn't indented. -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Here is a note reference,[^1] and another.[^longnote] -> -> [^1]: Here is the note. -> -> [^longnote]: Here's one with multiple blocks. -> -> Subsequent paragraphs are indented to show that they -> belong to the previous note. -> -> { some.code } -> -> The whole paragraph can be indented, or just the -> first line. In this way, multi-paragraph notes -> work like multi-paragraph list items. -> -> This paragraph won't be part of the note, because it -> isn't indented. - -%</manual-options> -%<*tex> -% \fi -% \begin{markdown} -% -% The footnotes option has been deprecated and will be removed in -% Markdown 3.0.0. -% -% \end{markdown} -% \begin{macrocode} -\@@_add_lua_option:nnn - { footnotes } - { boolean } - { false } -\@@_add_lua_option:nnn - { notes } - { boolean } - { false } -% \end{macrocode} -% \iffalse -%</tex> -%<*lua,lua-cli> -% \fi -% \begin{macrocode} -defaultOptions.footnotes = false -defaultOptions.notes = false -% \end{macrocode} -% \par -% \iffalse -%</lua,lua-cli> -%<*manual-options> - #### Option `frozenCacheCounter` `frozenCacheCounter` (default value: `0`) @@ -5883,12 +5952,6 @@ defaultOptions.hashEnumerators = false =================== `````` - These HTML attributes have currently no effect other than enabling -% content slicing, see the \Opt{slice} option. -% \iffalse - [content slicing](#slice). -% \fi - : false : Disable the assignment of HTML attributes to headings. @@ -6663,6 +6726,186 @@ defaultOptions.jekyllData = false %</lua,lua-cli> %<*manual-options> +#### Option `notes` + +`notes` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{notes}{\opt{true}, \opt{false}} +% +: true + + : Enable the Pandoc note syntax extension: + + ``` md + Here is a note reference,[^1] and another.[^longnote] + + [^1]: Here is the note. + + [^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they + belong to the previous note. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph notes + work like multi-paragraph list items. + + This paragraph won't be part of the note, because it + isn't indented. + `````` + +: false + + : Disable the Pandoc note syntax extension. + +% \end{markdown} +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[notes]{markdown} +\begin{document} +\begin{markdown} +Here is a note reference,[^1] and another.[^longnote] + +[^1]: Here is the note. + +[^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they +belong to the previous note. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph notes + work like multi-paragraph list items. + +This paragraph won't be part of the note, because it +isn't indented. +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Here is a note reference,[^1] and another.[^longnote] +> +> [^1]: Here is the note. +> +> [^longnote]: Here's one with multiple blocks. +> +> Subsequent paragraphs are indented to show that they +> belong to the previous note. +> +> { some.code } +> +> The whole paragraph can be indented, or just the +> first line. In this way, multi-paragraph notes +> work like multi-paragraph list items. +> +> This paragraph won't be part of the note, because it +> isn't indented. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\setupmarkdown[notes = yes] +\starttext +\startmarkdown +Here is a note reference,[^1] and another.[^longnote] + +[^1]: Here is the note. + +[^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they +belong to the previous note. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph notes + work like multi-paragraph list items. + +This paragraph won't be part of the note, because it +isn't indented. +\stopmarkdown +\stoptext +```````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Here is a note reference,[^1] and another.[^longnote] +> +> [^1]: Here is the note. +> +> [^longnote]: Here's one with multiple blocks. +> +> Subsequent paragraphs are indented to show that they +> belong to the previous note. +> +> { some.code } +> +> The whole paragraph can be indented, or just the +> first line. In this way, multi-paragraph notes +> work like multi-paragraph list items. +> +> This paragraph won't be part of the note, because it +> isn't indented. + +%</manual-options> +%<*tex> +% \fi +% \begin{markdown} +% +% The footnotes option has been deprecated and will be removed in +% Markdown 3.0.0. +% +% \end{markdown} +% \begin{macrocode} +\@@_add_lua_option:nnn + { footnotes } + { boolean } + { false } +\@@_add_lua_option:nnn + { notes } + { boolean } + { false } +% \end{macrocode} +% \iffalse +%</tex> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.footnotes = false +defaultOptions.notes = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `pipeTables` {#pipe-tables} `pipeTables` (default value: `false`) @@ -7132,7 +7375,7 @@ defaultOptions.shiftHeadings = 0 %</lua,lua-cli> %<*manual-options> -#### Option `slice` {#slice} +#### Option `slice` `slice` (default value: `^ $`) @@ -9042,7 +9285,7 @@ pdftex --shell-escape document.tex % \input markdown % ``````` % \noindent It is expected that the special plain \TeX{} characters have the -% expected category codes, when \mref{input}ting the file. +% expected category codes, when `\input`ting the file. % %### Typesetting Markdown {#textypesetting} % @@ -9208,7 +9451,7 @@ following code in your plain \TeX{} document: %#### Finalizing and Freezing the Cache % The \mdef{markdownOptionFinalizeCache} option corresponds to the Lua % interface \Opt{finalizeCache} option, which creates an output file -% \mref{markdownOptionFrozenCacheFileName} (frozen cache) that contains a mapping +% \Opt{frozenCacheFileName} (frozen cache) that contains a mapping % between an enumeration of the markdown documents in the plain \TeX{} document % and their auxiliary files cached in the \Opt{cacheDir} directory. % @@ -9221,7 +9464,7 @@ following code in your plain \TeX{} document: % \fi % The \mdef{markdownOptionFrozenCache} option uses the mapping previously -% created by the \mref{markdownOptionFinalizeCache} option, +% created by the \Opt{finalizeCache} option, % \iffalse created by the Lua interface \Opt{finalizeCache} option, % \fi @@ -9255,12 +9498,12 @@ options is as follows: 1. Remove the \Opt{cacheDir} cache directory with stale auxiliary cache files. -% 2. Enable the \mref{markdownOptionFinalizeCache} option. +% 2. Enable the \Opt{finalizeCache} option. % \iffalse 2. Enable the \Opt{finalizeCache} option. % \fi 3. Typeset the plain \TeX{} document to populate and finalize the cache. -4. Enable the \mref{markdownOptionFrozenCache} option. +4. Enable the \Opt{frozenCache} option. 5. Publish the source code of the plain \TeX{} document and the \Opt{cacheDir} directory. @@ -9279,13 +9522,13 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionHelperScriptFileName} macro sets the filename of the % helper Lua script file that is created during the conversion from markdown to -% plain \TeX{} in \TeX{} engines without the \mref{directlua} primitive. It -% defaults to \mref{jobname}`.markdown.lua`, where \mref{jobname} is the base name +% plain \TeX{} in \TeX{} engines without the `\directlua` primitive. It +% defaults to `\jobname.markdown.lua`, where `\jobname` is the base name % of the document being typeset. % % The expansion of this macro must not contain quotation marks (`"`) or % backslash symbols (`\`). Mind that \TeX{} engines tend to -% put quotation marks around \mref{jobname}, when it contains spaces. +% put quotation marks around `\jobname`, when it contains spaces. % % \end{markdown} % \begin{macrocode} @@ -9297,10 +9540,10 @@ For more information, see the examples for the \Opt{finalizeCache} option. % \par % \begin{markdown} % -% The \mref{markdownOptionHelperScriptFileName} macro has been deprecated and +% The \Opt{helperScriptFileName} macro has been deprecated and % will be removed in Markdown 3.0.0. To control the filename of the helper Lua -% script file, use the \mref{g_luabridge_helper_script_filename_str} macro -% from the \pkg{lt3luabridge} package. +% script file, use the `\g_luabridge_helper_script_filename_str` macro from the +% \pkg{lt3luabridge} package. % % \end{markdown} % \begin{macrocode} @@ -9314,8 +9557,8 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % The \mdef{markdownOptionInputTempFileName} macro sets the filename of the % temporary input file that is created during the buffering of markdown text -% from a \TeX{} source. It defaults to \mref{jobname}`.markdown.in`. The same -% limitations as in the case of the \mref{markdownOptionHelperScriptFileName} +% from a \TeX{} source. It defaults to `\jobname.markdown.in`. The same +% limitations as in the case of the \Opt{helperScriptFileName} % macro apply here. % % \end{markdown} @@ -9331,8 +9574,8 @@ For more information, see the examples for the \Opt{finalizeCache} option. % The \mdef{markdownOptionOutputTempFileName} macro sets the filename of the % temporary output file that is created during the conversion from markdown to % plain \TeX{} in \mref{markdownMode} other than `2` It defaults to -% \mref{jobname}`.markdown.out`. The same limitations apply here as in the case -% of the \mref{markdownOptionHelperScriptFileName} macro. +% `\jobname.markdown.out`. The same limitations apply here as in the case +% of the \Opt{helperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -9344,7 +9587,7 @@ For more information, see the examples for the \Opt{finalizeCache} option. % \par % \begin{markdown} % -% The \mref{markdownOptionOutputTempFileName} macro has been deprecated and +% The \Opt{outputTempFileName} macro has been deprecated and % will be removed in Markdown 3.0.0. % % \end{markdown} @@ -9360,8 +9603,8 @@ For more information, see the examples for the \Opt{finalizeCache} option. % The \mdef{markdownOptionErrorTempFileName} macro sets the filename of the % temporary output file that is created when a Lua error is encountered during % the conversion from markdown to plain \TeX{} in \mref{markdownMode} other than -% `2`. It defaults to \mref{jobname}`.markdown.err`. The same limitations -% apply here as in the case of the \mref{markdownOptionHelperScriptFileName} +% `2`. It defaults to `\jobname.markdown.err`. The same limitations +% apply here as in the case of the \Opt{helperScriptFileName} % macro. % % \end{markdown} @@ -9374,10 +9617,10 @@ For more information, see the examples for the \Opt{finalizeCache} option. % \par % \begin{markdown} % -% The \mref{markdownOptionErrorTempFileName} macro has been deprecated and +% The \Opt{errorTempFileName} macro has been deprecated and % will be removed in Markdown 3.0.0. To control the filename of the temporary -% file for Lua errors, use the \mref{g_luabridge_error_output_filename_str} -% macro from the \pkg{lt3luabridge} package. +% file for Lua errors, use the `\g_luabridge_error_output_filename_str` macro +% from the \pkg{lt3luabridge} package. % % \end{markdown} % \begin{macrocode} @@ -9398,7 +9641,7 @@ For more information, see the examples for the \Opt{finalizeCache} option. % your \TeX{} engine for the package to function correctly. We need this macro % to make the Lua implementation aware where it should store the helper files. % The same limitations apply here as in the case of the -% \mref{markdownOptionHelperScriptFileName} macro. +% \Opt{helperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -9419,7 +9662,7 @@ For more information, see the examples for the \Opt{finalizeCache} option. % % For the macros that correspond to the non-boolean options recognized by the % Lua interface, the same limitations apply here in the case of the -% \mref{markdownOptionHelperScriptFileName} macro. +% \Opt{helperScriptFileName} macro. % % \end{markdown} % \begin{macrocode} @@ -9690,119 +9933,6 @@ In this section, I will describe the individual token renderers. \prop_new:N \g_@@_renderer_arities_prop \ExplSyntaxOff % \end{macrocode} -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% \begin{markdown} - -#### Tickbox Renderers -The macros named \mdef{markdownRendererTickedBox}, -\mdef{markdownRendererHalfTickedBox}, and \mdef{markdownRendererUntickedBox} -represent ticked and unticked boxes, respectively. These macros will either be -produced, when the \Opt{taskLists} option is enabled, or when the Ballot Box -with X (☒, U+2612), Hourglass (⌛, U+231B) or Ballot Box (☐, U+2610) Unicode -characters are encountered in the markdown input, respectively. - -% \end{markdown} -% -% \iffalse - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[taskLists]{markdown} -\markdownSetup{ - renderers = { - untickedBox = No, - tickedBox = Yes, - }, -} -\begin{document} -\begin{markdown} -- [ ] you can't. -- [x] I can! -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> - No you can't. -> - Yes I can! - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\setupmarkdown[taskLists = yes] -\def\markdownRendererUntickedBox{No} -\def\markdownRendererTickedBox{Yes} -\starttext -\startmarkdown -- [ ] you can't. -- [x] I can! -\stopmarkdown -\stoptext -```````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> - No you can't. -> - Yes I can! - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererTickedBox{% - \markdownRendererTickedBoxPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { tickedBox } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { tickedBox } - { 0 } -\ExplSyntaxOff -\def\markdownRendererHalfTickedBox{% - \markdownRendererHalfTickedBoxPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { halfTickedBox } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { halfTickedBox } - { 0 } -\ExplSyntaxOff -\def\markdownRendererUntickedBox{% - \markdownRendererUntickedBoxPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { untickedBox } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { untickedBox } - { 0 } -\ExplSyntaxOff -% \end{macrocode} % \par % % \iffalse @@ -9812,15 +9942,25 @@ following text: % % \begin{markdown} -#### Markdown Document Renderers -The \mdef{markdownRendererDocumentBegin} and \mdef{markdownRendererDocumentEnd} -macros represent the beginning and the end of a *markdown* document. The macros -receive no arguments. +#### Attribute Renderers +The following macros are only produced, when the \Opt{headerAttributes} option +is enabled. -A \TeX{} document may contain any number of markdown documents. Additionally, -markdown documents may appear not only in a sequence, but several markdown -documents may also be *nested*. Redefinitions of the macros should take this -into account. +\mdef{markdownRendererAttributeIdentifier} represents the \meta{identifier} of +a markdown element (`id="`\meta{identifier}`"` in HTML and `#`\meta{identifier} +in Markdown's \Opt{headerAttributes} syntax extension). The macro receives a +single attribute that corresponds to the \meta{identifier}. + +\mdef{markdownRendererAttributeClassName} represents the \meta{class name} of a +markdown element (`class="`\meta{class name} ...`"` in HTML and +`.`\meta{class name} in Markdown's \Opt{headerAttributes} syntax extension). +The macro receives a single attribute that corresponds to the \meta{class +name}. + +\mdef{markdownRendererAttributeKeyValue} represents a HTML attribute in the form +\meta{key}`=`\meta{value} that is neither an identifier nor a class name. +The macro receives two attributes that correspond to the \meta{key} and the +\meta{value}, respectively. % \end{markdown} % @@ -9828,75 +9968,38 @@ into account. ##### \LaTeX{} Example {.unnumbered} -Using a text editor, create a text document named `nested.md` with the -following content: -``` md -This is a *nested* markdown document. -``` - Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[contentBlocks]{markdown} +\usepackage[headerAttributes, underscores=false]{markdown} \markdownSetup{ renderers = { - contentBlock = {% - \markdownInput{#3}% - }, - documentBegin = {% - \par - \emph{(The beginning of a document)} - \par - \begingroup - \markdownSetup{snippet=first-nesting-level}% - }, - documentEnd = {% - \endgroup - \par - \emph{(The end of a document)} - \par - }, - }, -} -\markdownSetupSnippet{first-nesting-level}{ - renderers = { - documentBegin = { + attributeIdentifier = {% \par - \emph{(The beginning of a nested document)} + \emph{(Identifier: #1)} \par - \begingroup - \markdownSetup{snippet=second-nesting-level-and-below} }, - }, -} -\markdownSetupSnippet{second-nesting-level-and-below}{ - renderers = { - documentBegin = { + attributeClassName = {% \par - \emph{(The beginning of a nested document)} + \emph{(Class name: #1)} \par - \begingroup }, - documentEnd = { - \endgroup + attributeKeyValue = {% \par - \emph{(The end of a nested document)} + \emph{(Key: #1, Value: #2)} \par }, }, } \begin{document} \begin{markdown} -Hello *world*! -/nested.md +# First top-level heading {jane=doe} -_Foo_ bar! -\end{markdown} -\begin{markdown} +## A subheading {#identifier} -Bar baz! +# Second top-level heading {.class_name} \end{markdown} \end{document} @@ -9908,186 +10011,55 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> *(The beginning of a document)* -> -> Hello *world*! -> -> *(The beginning of a nested document)* -> -> This is a *nested* markdown document. -> -> *(The end of a nested document)* +> # First top-level heading > -> _Foo_ bar! +> *(Key: Jane, Value: Doe)* > -> *(The end of a document)* +> ## A subheading > -> *(The beginning of a document)* +> *(Identifier: identifier)* > -> Bar baz! +> # Second top-level heading > -> *(The end of a document)* +> *(Class name: class\_name)* %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererDocumentBegin{% - \markdownRendererDocumentBeginPrototype}% +\def\markdownRendererAttributeIdentifier{% + \markdownRendererAttributeIdentifierPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { documentBegin } + { attributeIdentifier } \prop_gput:Nnn \g_@@_renderer_arities_prop - { documentBegin } - { 0 } + { attributeIdentifier } + { 1 } \ExplSyntaxOff -\def\markdownRendererDocumentEnd{% - \markdownRendererDocumentEndPrototype}% +\def\markdownRendererAttributeClassName{% + \markdownRendererAttributeClassNamePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { documentEnd } + { attributeClassName } \prop_gput:Nnn \g_@@_renderer_arities_prop - { documentEnd } - { 0 } + { attributeClassName } + { 1 } \ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Interblock Separator Renderer -The \mdef{markdownRendererInterblockSeparator} macro represents a separator -between two markdown block elements. The macro receives no arguments. - -% \end{markdown} -% -% \iffalse - -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererInterblockSeparator{% - \par - {\it(The end of a block)}% - \par -} -\markdownBegin -Hello *world*! - -_Foo_ bar! -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(The end of a block)* -> -> _Foo_ bar! - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\markdownSetup{ - renderers = { - interblockSeparator = {% - \par - \emph{(The end of a block)}% - \par - }, - }, -} -\begin{document} -\begin{markdown} -Hello *world*! - -_Foo_ bar! -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(The end of a block)* -> -> _Foo_ bar! - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownRendererInterblockSeparator{% - \par - \emph{(The end of a block)}% - \par -} -\starttext -\startmarkdown -Hello *world*! - -_Foo_ bar! -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(The end of a block)* -> -> _Foo_ bar! - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererInterblockSeparator{% - \markdownRendererInterblockSeparatorPrototype}% +\def\markdownRendererAttributeKeyValue{% + \markdownRendererAttributeKeyValuePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { interblockSeparator } + { attributeKeyValue } \prop_gput:Nnn \g_@@_renderer_arities_prop - { interblockSeparator } - { 0 } + { attributeKeyValue } + { 2 } \ExplSyntaxOff % \end{macrocode} % \par @@ -10099,140 +10071,27 @@ following text: % % \begin{markdown} -#### Line Break Renderer -The \mdef{markdownRendererLineBreak} macro represents a forced line break. -The macro receives no arguments. +#### Block Quote Renderers +The \mdef{markdownRendererBlockQuoteBegin} macro represents the beginning of +a block quote. The macro receives no arguments. % \end{markdown} % % \iffalse - -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererLineBreak{% - \par - {\it(A forced linebreak)}% - \par -} -\markdownInput{example.md} -\bye -``````` -Using a text editor, create a text document named `example.md` with the -following content. Note the two spaces at the end of the first line, which -specify a hard linebreak. Due to the limitations of the \TeX{} input -processor, hard linebreaks would be ignored if we typed them directly into the -`document.tex` document. - -<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> - -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(A forced linebreak)* -> -> _Foo_ bar! - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\markdownSetup{ - renderers = { - lineBreak = {% - \par - \emph{(A forced linebreak)}% - \par - }, - }, -} -\begin{document} -\markdownInput{example.md} -\end{document} -``````` -Using a text editor, create a text document named `example.md` with the -following content. Note the two spaces at the end of the first line, which -specify a hard linebreak. Due to the limitations of the \TeX{} input -processor, hard linebreaks would be ignored if we typed them directly into the -`document.tex` document. - -<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> - -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(A forced linebreak)* -> -> _Foo_ bar! - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownRendererLineBreak{% - \par - \emph{(A forced linebreak)}% - \par -} -\starttext -\markdownInput{example.md} -\stoptext -``````` -Using a text editor, create a text document named `example.md` with the -following content. Note the two spaces at the end of the first line, which -specify a hard linebreak. Due to the limitations of the \TeX{} input -processor, hard linebreaks would be ignored if we typed them directly into the -`document.tex` document. - -<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> - -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(A forced linebreak)* -> -> _Foo_ bar! - %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererLineBreak{% - \markdownRendererLineBreakPrototype}% +\def\markdownRendererBlockQuoteBegin{% + \markdownRendererBlockQuoteBeginPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { lineBreak } + { blockQuoteBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { lineBreak } + { blockQuoteBegin } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -10245,10 +10104,8 @@ following text: % % \begin{markdown} -#### Ellipsis Renderer -The \mdef{markdownRendererEllipsis} macro replaces any occurance of ASCII -ellipses in the input text. This macro will only be produced, when the -\Opt{smartEllipses} option is enabled. The macro receives no arguments. +The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block +quote. The macro receives no arguments. % \end{markdown} % @@ -10260,452 +10117,25 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownOptionSmartEllipses{true} -\def\markdownRendererEllipsis{{\it SHAZAM}!} -\markdownBegin -The secret word is ... -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The secret word is *SHAZAM*! - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[smartEllipses]{markdown} -\markdownSetup{ - renderers = { - ellipsis = \emph{SHAZAM}!, - }, -} -\begin{document} -\begin{markdown} -The secret word is ... -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The secret word is *SHAZAM*! - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\setupmarkdown[smartEllipses = yes] -\def\markdownRendererEllipsis{\emph{SHAZAM}!} -\starttext -\startmarkdown -The secret word is ... -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Hello *world*! -> -> *(The end of a block)* -> -> _Foo_ bar! - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererEllipsis{% - \markdownRendererEllipsisPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { ellipsis } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { ellipsis } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Non-Breaking Space Renderer -The \mdef{markdownRendererNbsp} macro represents a non-breaking space. - -% \end{markdown} -% -% \iffalse - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.bib` with the -following content: -``` bib -@book{knuth:tex, - author = "Knuth, Donald Ervin", - title = "The \TeX book, volume A of Computers and typesetting", - publisher = "Addison-Wesley", - year = "1984" -} -``````` -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[ - citations, - citationNbsps, -]{markdown} -\markdownSetup{ - renderers = { - nbsp = {$\cdot$}, - }, +\def\markdownRendererBlockQuoteBegin{% + \begingroup + \vskip\parindent + \leftskip=2\parindent + \parindent=0pt } -\begin{document} - -\begin{markdown} -The TeXbook [@knuth:tex, p. 123 and 130] is good. -\end{markdown} - -\bibliographystyle{plain} -\bibliography{document.bib} - -\end{document} -``````` -Next, invoke LuaTeX and BibTeX from the terminal: -``` sh -lualatex document.tex -bibtex document.aux -lualatex document.tex -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> The TeXbook [1, p.·123·and·130] is good. -> -> ### References -> [1] Donald Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._ -> Addison-Wesley, 1984. - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererNbsp{% - \markdownRendererNbspPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { nbsp } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { nbsp } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Special Character Renderers -The following macros replace any special plain \TeX{} characters, including -% \iffalse -the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text: - -- \mdef{markdownRendererAmpersand} replaces the ampersand (`&`). -- \mdef{markdownRendererBackslash} replaces the backslash (`\`). -- \mdef{markdownRendererCircumflex} replaces the circumflex (`^`). -- \mdef{markdownRendererDollarSign} replaces the dollar sign (`$`). -- \mdef{markdownRendererHash} replaces the hash sign (`#`). -- \mdef{markdownRendererLeftBrace} replaces the left brace (`{`). -- \mdef{markdownRendererPercentSign} replaces the percent sign (`%`). -- \mdef{markdownRendererPipe} replaces the pipe character (`|`). -- \mdef{markdownRendererRightBrace} replaces the right brace (`}`). -- \mdef{markdownRendererTilde} replaces the tilde (`~`). -- \mdef{markdownRendererUnderscore} replaces the underscore (`_`). - -% \fi -% the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text. -% These macros will only be produced, when the \Opt{hybrid} option is -% `false`. - -% \end{markdown} -% -% \iffalse - -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content. We will make the tilde behave as if it were written in -\TeX{}, where it represents a non-breaking space. -``` tex -\input markdown -\def\markdownRendererTilde{~} -\markdownBegin -Bartel~Leendert van~der~Waerden -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text, where the middot (`·`) denotes a non-breaking space: - -> Bartel·Leendert van·der·Waerden - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content. We will make the tilde behave as if it were written in -\TeX{}, where it represents a non-breaking space. -``` tex -\documentclass{article} -\usepackage{markdown} -\markdownSetup{ - renderers = { - tilde = ~, - }, +\def\markdownRendererBlockQuoteEnd{% + \par + \vskip\parindent + \endgroup } -\begin{document} -\begin{markdown} -Bartel~Leendert van~der~Waerden -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text, where the middot (`·`) denotes a non-breaking space: - -> Bartel·Leendert van·der·Waerden - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content. We will make the tilde behave as if it were written in -\TeX{}, where it represents a non-breaking space. -``` tex -\usemodule[t][markdown] -\def\markdownRendererTilde{~} -\starttext -\startmarkdown -Bartel~Leendert van~der~Waerden -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text, where the middot (`·`) denotes a non-breaking space: - -> Bartel·Leendert van·der·Waerden - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererLeftBrace{% - \markdownRendererLeftBracePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { leftBrace } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { leftBrace } - { 0 } -\ExplSyntaxOff -\def\markdownRendererRightBrace{% - \markdownRendererRightBracePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { rightBrace } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { rightBrace } - { 0 } -\ExplSyntaxOff -\def\markdownRendererDollarSign{% - \markdownRendererDollarSignPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { dollarSign } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { dollarSign } - { 0 } -\ExplSyntaxOff -\def\markdownRendererPercentSign{% - \markdownRendererPercentSignPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { percentSign } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { percentSign } - { 0 } -\ExplSyntaxOff -\def\markdownRendererAmpersand{% - \markdownRendererAmpersandPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { ampersand } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { ampersand } - { 0 } -\ExplSyntaxOff -\def\markdownRendererUnderscore{% - \markdownRendererUnderscorePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { underscore } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { underscore } - { 0 } -\ExplSyntaxOff -\def\markdownRendererHash{% - \markdownRendererHashPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { hash } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { hash } - { 0 } -\ExplSyntaxOff -\def\markdownRendererCircumflex{% - \markdownRendererCircumflexPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { circumflex } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { circumflex } - { 0 } -\ExplSyntaxOff -\def\markdownRendererBackslash{% - \markdownRendererBackslashPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { backslash } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { backslash } - { 0 } -\ExplSyntaxOff -\def\markdownRendererTilde{% - \markdownRendererTildePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { tilde } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { tilde } - { 0 } -\ExplSyntaxOff -\def\markdownRendererPipe{% - \markdownRendererPipePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { pipe } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { pipe } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Code Span Renderer -The \mdef{markdownRendererCodeSpan} macro represents inline code span in the -input text. It receives a single argument that corresponds to the inline -code span. - -% \end{markdown} -% -% \iffalse - -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\input lmfonts - -\def\markdownRendererCodeSpan#1{#1} - \markdownBegin -`$\sqrt{-1}$ *equals* $i$` - -$\sqrt{-1}$ *equals* $i$ -\markdownEnd +A quote from William Shakespeare's King Lear: -\def\markdownOptionHybrid{true} -\markdownBegin -$\sqrt{-1}$ *equals* $i$ +> This is the excellent foppery of the world that when we are +> sick in fortune---often the surfeit of our own behavior---we +> make guilty of our disasters the sun, the moon, and the +> stars [...] \markdownEnd - \bye ``````` Next, invoke LuaTeX from the terminal: @@ -10715,11 +10145,12 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> \$\\sqrt{-1}\$ \*equals\* \$i\$. -> -> \$\\sqrt{-1}\$ *equals* \$i\$. -> -> √-̅1̅ *equals* $i$. +> A quote from William Shakespeare's King Lear: +> +> > This is the excellent foppery of the world that when we are +> > sick in fortune—often the surfeit of our own behavior—we +> > make guilty of our disasters the sun, the moon, and the +> > stars [...] ##### \LaTeX{} Example {.unnumbered} @@ -10727,24 +10158,22 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[smartEllipses]{markdown} +\usepackage{markdown} \markdownSetup{ renderers = { - codeSpan = {#1}, + blockQuoteBegin = {\begin{quote}}, + blockQuoteEnd = {\end{quote}}, }, } \begin{document} - \begin{markdown} -`$\sqrt{-1}$ *equals* $i$` +A quote from William Shakespeare's King Lear: -$\sqrt{-1}$ *equals* $i$ +> This is the excellent foppery of the world that when we are +> sick in fortune---often the surfeit of our own behavior---we +> make guilty of our disasters the sun, the moon, and the +> stars [...] \end{markdown} - -\begin{markdown*}{hybrid} -$\sqrt{-1}$ *equals* $i$ -\end{markdown*} - \end{document} ``````` Next, invoke LuaTeX from the terminal: @@ -10754,11 +10183,12 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> \$\\sqrt{-1}\$ \*equals\* \$i\$. -> -> \$\\sqrt{-1}\$ *equals* \$i\$. -> -> √-̅1̅ *equals* $i$. +> A quote from William Shakespeare's King Lear: +> +> > This is the excellent foppery of the world that when we are +> > sick in fortune—often the surfeit of our own behavior—we +> > make guilty of our disasters the sun, the moon, and the +> > stars [...] ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -10766,21 +10196,18 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\def\markdownRendererCodeSpan#1{#1} +\def\markdownRendererBlockQuoteBegin{\startquotation} +\def\markdownRendererBlockQuoteEnd{\stopquotation} \starttext - \startmarkdown -`$\sqrt{-1}$ *equals* $i$` - -$\sqrt{-1}$ *equals* $i$ -\stopmarkdown +A quote from William Shakespeare's King Lear: -\setupmarkdown[hybrid = yes] -\startmarkdown -$\sqrt{-1}$ *equals* $i$ +> This is the excellent foppery of the world that when we are +> sick in fortune---often the surfeit of our own behavior---we +> make guilty of our disasters the sun, the moon, and the +> stars [...] \stopmarkdown - -\bye +\stoptext ``````` Next, invoke LuaTeX from the terminal: ``` sh @@ -10789,27 +10216,28 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> \$\\sqrt{-1}\$ \*equals\* \$i\$. -> -> \$\\sqrt{-1}\$ *equals* \$i\$. -> -> √-̅1̅ *equals* $i$. +> A quote from William Shakespeare's King Lear: +> +> > This is the excellent foppery of the world that when we are +> > sick in fortune—often the surfeit of our own behavior—we +> > make guilty of our disasters the sun, the moon, and the +> > stars [...] %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererCodeSpan{% - \markdownRendererCodeSpanPrototype}% +\def\markdownRendererBlockQuoteEnd{% + \markdownRendererBlockQuoteEndPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { codeSpan } + { blockQuoteEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { codeSpan } - { 1 } + { blockQuoteEnd } + { 0 } \ExplSyntaxOff % \end{macrocode} % \par @@ -10821,63 +10249,37 @@ following text: % % \begin{markdown} -#### Link Renderer -The \mdef{markdownRendererLink} macro represents a hyperlink. It receives -four arguments: the label, the fully escaped \acro{uri} that can be directly -typeset, the raw \acro{uri} that can be used outside typesetting, and the -title of the link. +#### Bracketed Spans Context Renderers +The following macros are only produced, when the \Opt{bracketedSpans} option is +enabled. + +The \mdef{markdownRendererBracketedSpanAttributeContextBegin} and +\mdef{markdownRendererBracketedSpanAttributeContextEnd} macros represent the +beginning and the end of an inline bracketed span in which the attributes of +the span apply. The macros receive no arguments. % \end{markdown} % % \iffalse -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownRendererLink#1#2#3#4{% - #1 {\tt#2} titled {\it#4}% -} -\markdownBegin -Please visit [the link][ctan]. - - [ctan]: https://ctan.org/ - (the Comprehensive TeX Archive Network) -\markdownEnd -\bye -``````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX -> Archive Network*. - ##### \LaTeX{} Example {.unnumbered} Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage{markdown} +\usepackage[bracketedSpans]{markdown} \markdownSetup{ renderers = { - link = {% - #1 \texttt{#2} titled \emph{#4}% - }, + fencedDivAttributeContextBegin = {(}, + fencedDivAttributeContextEnd = {)}, }, } \begin{document} \begin{markdown} -Please visit [the link][ctan]. - [ctan]: https://ctan.org/ - (the Comprehensive TeX Archive Network) +[foo [bar]{#identifier}]{key=value} [baz]{.class_name} + \end{markdown} \end{document} ``````` @@ -10888,407 +10290,34 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX -> Archive Network*. - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\def\markdownRendererLink#1#2#3#4{% - #1 {\tt#2} titled \emph{#4}% -} -\starttext -\startmarkdown -Please visit [the link][ctan]. - - [ctan]: https://ctan.org/ - (the Comprehensive TeX Archive Network) -\stopmarkdown -\stoptext -``````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX -> Archive Network*. +> (foo (bar)) (baz) %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererLink{% - \markdownRendererLinkPrototype}% +\def\markdownRendererBracketedSpanAttributeContextBegin{% + \markdownRendererBracketedSpanAttributeContextBeginPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { link } + { bracketedSpanAttributeContextBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { link } - { 4 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Image Renderer -The \mdef{markdownRendererImage} macro represents an image. It receives -four arguments: the label, the fully escaped \acro{uri} that can be directly -typeset, the raw \acro{uri} that can be used outside typesetting, and the -title of the link. - -% \end{markdown} -% -% \iffalse - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage{markdown} -\begingroup -\catcode`\@=11 -\catcode`\%=12 -\catcode`\^^A=14 -\global\def\markdownRendererImage#1#2#3#4{^^A - \immediate\write18{^^A -``` -``` sh - if printf '%s' "#3" | grep -q ^http; then - OUTPUT="$(printf '%s' "#3" | md5sum | cut -d' ' -f1).^^A - $(printf '%s' "#3" | sed 's/.*[.]//')"; - if ! [ -e "$OUTPUT" ]; then - wget -O "$OUTPUT" '#3' || rm "$OUTPUT"; - convert "$OUTPUT" png:"$OUTPUT"; - fi; - printf '%s%%' "$OUTPUT" > \jobname.fetched; - else - printf '%s%%' "#3" > \jobname.fetched; - fi^^A -``` -``` tex - }^^A - {^^A - \everyeof={\noexpand}^^A - \edef\filename{\@@input"\jobname.fetched" }^^A - \includegraphics[width=\textwidth]{\filename}^^A - }^^A -} -\endgroup -\begin{document} -\begin{markdown} -![TUGboat](https://tug.org/tugboat/noword.jpg) -\end{markdown} -\end{document} -`````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex --shell-escape document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following content. This assumes that you use a Unix-like operating system with -Bourne or Bourne again shell as the default shell of the current user. It also -assumes that the `md5sum`, `wget`, and `convert` binaries are installed and -that the \TeX{} engine has shell access. - -> ![TUGboat](https://tug.org/tugboat/noword.jpg "The Communications of the TeX Users Group") - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererImage{% - \markdownRendererImagePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { image } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { image } - { 4 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Content Block Renderers {#texcontentblockrenderers} - -The \mdef{markdownRendererContentBlock} macro represents an iA\,Writer content -block. It receives four arguments: the local file or online image filename -extension cast to the lower case, the fully escaped \acro{uri} that can be -directly typeset, the raw \acro{uri} that can be used outside typesetting, -and the title of the content block. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererContentBlock{% - \markdownRendererContentBlockPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { contentBlock } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { contentBlock } - { 4 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -The \mdef{markdownRendererContentBlockOnlineImage} macro represents an -iA\,Writer online image content block. The macro receives the same arguments -as \mref{markdownRendererContentBlock}. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererContentBlockOnlineImage{% - \markdownRendererContentBlockOnlineImagePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { contentBlockOnlineImage } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { contentBlockOnlineImage } - { 4 } + { bracketedSpanAttributeContextBegin } + { 0 } \ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -The \mdef{markdownRendererContentBlockCode} macro represents an iA\,Writer -content block that was recognized as a file in a known programming language -by its filename extension $s$. If any `markdown-languages.json` file found -by \pkg{kpathsea}^[Filenames other than `markdown-languages.json` may -be specified using the `contentBlocksLanguageMap` Lua option.] contains a -record $(k, v)$, then a non-online-image content block with the filename -extension $s, s$`:lower()`${}=k$ is considered to be in a known programming -language $v$. -The macro receives five arguments: the local file name extension $s$ cast to -the lower case, the language $v$, the fully escaped \acro{uri} that can be -directly typeset, the raw \acro{uri} that can be used outside typesetting, -and the title of the content block. - -Note that you will need to place place a `markdown-languages.json` file -inside your working directory or inside your local \TeX{} directory -structure. In this file, you will define a mapping between filename -extensions and the language names recognized by your favorite syntax -highlighter; there may exist other creative uses beside syntax highlighting. -% The `Languages.json` file provided by @sotkov17 is a good starting point. -% \end{markdown} -% -% \iffalse -[The `Languages.json` file provided by Anton Sotkov][sotkov17] is a good -starting point. - - [sotkov17]: https://github.com/iainc/Markdown-Content-Blocks - (File transclusion syntax for Markdown) - -##### Plain \TeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\input markdown -\def\markdownOptionContentBlocks{true} -\def\markdownRendererContentBlock#1#2#3#4{% - This is {\tt #2}, #4. -} -\def\markdownRendererContentBlockOnlineImage#1#2#3#4{% - This is the image {\tt #2}, #4. -} -\def\markdownRendererContentBlockCode#1#2#3#4#5{% - This is the #2 (\uppercase{#1}) document {\tt #3}, #5. -} -\markdownBegin -/document.tex (the document that we are currently typesetting) -/markdown-languages.json (the mapping between filename extensions - and programming language names) -https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) -\markdownEnd -\bye -``````` -Create also a text document named `markdown-languages.json` with the following -content: -``` js -{ - "json": "JavaScript Object Notation", -} -`````` -Next, invoke LuaTeX from the terminal: -``` sh -luatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is `document.tex`, the document that we are currently typesetting. -> -> This is the JavaScript Object Notation (JSON) document -> `markdown-languages.json`, the mapping between filename extensions and -> programming language names. -> -> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of -> TUGboat. - -##### \LaTeX{} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\begin{filecontents}[overwrite,nosearch,noheader]{markdown-languages.json} -{ - "json": "JavaScript Object Notation", -} -\end{filecontents} -\usepackage[contentBlocks]{markdown} -\markdownSetup{ - renderers = { - contentBlock = {This is \texttt{#2}, #4.}, - contentBlockOnlineImage = {This is the image \texttt{#2}, #4.}, - contentBlockCode = {% - This is the #2 (\MakeUppercase{#1}) document \texttt{#3}, #5. - }, - }, -} -\begin{document} -\begin{markdown} -/document.tex (the document that we are currently typesetting) -/markdown-languages.json (the mapping between filename extensions - and programming language names) -https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is `document.tex`, the document that we are currently typesetting. -> -> This is the JavaScript Object Notation (JSON) document -> `markdown-languages.json`, the mapping between filename extensions and -> programming language names. -> -> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of -> TUGboat. - -##### \Hologo{ConTeXt} Example {.unnumbered} - -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\usemodule[t][markdown] -\setupmarkdown[contentBlocks = yes] -\def\markdownRendererContentBlock#1#2#3#4{% - This is {\tt #2}, #4. -} -\def\markdownRendererContentBlockOnlineImage#1#2#3#4{% - This is the image {\tt #2}, #4. -} -\def\markdownRendererContentBlockCode#1#2#3#4#5{% - This is the #2 (\uppercase{#1}) document {\tt #3}, #5. -} -\starttext -\startmarkdown -/document.tex (the document that we are currently typesetting) -/markdown-languages.json (the mapping between filename extensions - and programming language names) -https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) -\stopmarkdown -\stoptext -``````` -Create also a text document named `markdown-languages.json` with the following -content: -``` js -{ - "json": "JavaScript Object Notation", -} -`````` -Next, invoke LuaTeX from the terminal: -``` sh -context document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: - -> This is `document.tex`, the document that we are currently typesetting. -> -> This is the JavaScript Object Notation (JSON) document -> `markdown-languages.json`, the mapping between filename extensions and -> programming language names. -> -> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of -> TUGboat. - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererContentBlockCode{% - \markdownRendererContentBlockCodePrototype}% +\def\markdownRendererBracketedSpanAttributeContextEnd{% + \markdownRendererBracketedSpanAttributeContextEndPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { contentBlockCode } + { bracketedSpanAttributeContextEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { contentBlockCode } - { 5 } + { bracketedSpanAttributeContextEnd } + { 0 } \ExplSyntaxOff % \end{macrocode} % \par @@ -11701,11 +10730,10 @@ following text: % % \begin{markdown} -#### Ordered List Renderers -The \mdef{markdownRendererOlBegin} macro represents the beginning of an -ordered list that contains an item with several paragraphs of text (the -list is not tight). This macro will only be produced, when the \Opt{fancyLists} -option is disabled. The macro receives no arguments. +#### Code Block Renderers +The \mdef{markdownRendererInputVerbatim} macro represents a code +block. The macro receives a single argument that corresponds to the +filename of a file contaning the code block contents. % \end{markdown} % @@ -11715,16 +10743,16 @@ option is disabled. The macro receives no arguments. % \fi % % \begin{macrocode} -\def\markdownRendererOlBegin{% - \markdownRendererOlBeginPrototype}% +\def\markdownRendererInputVerbatim{% + \markdownRendererInputVerbatimPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { olBegin } + { inputVerbatim } \prop_gput:Nnn \g_@@_renderer_arities_prop - { olBegin } - { 0 } + { inputVerbatim } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -11736,103 +10764,110 @@ option is disabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererOlBeginTight} macro represents the beginning of an -ordered list that contains no item with several paragraphs of text (the -list is tight). This macro will only be produced, when the \Opt{tightLists} -option is enabled and the \Opt{fancyLists} option is disabled. The macro -receives no arguments. +The \mdef{markdownRendererInputFencedCode} macro represents a fenced code +block. This macro will only be produced, when the \Opt{fencedCode} option is +enabled. The macro receives two arguments that correspond to the filename of +a file contaning the code block contents and to the code fence infostring. % \end{markdown} % % \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererOlBeginTight{% - \markdownRendererOlBeginTightPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { olBeginTight } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { olBeginTight } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} -The \mdef{markdownRendererFancyOlBegin} macro represents the beginning of a -fancy ordered list that contains an item with several paragraphs of text (the -list is not tight). This macro will only be produced, when the \Opt{fancyLists} -option is enabled. The macro receives two arguments: the style of the list item -labels (`Decimal`, `LowerRoman`, `UpperRoman`, `LowerAlpha`, and `UpperAlpha`), -and the style of delimiters between list item labels and texts (`Default`, -`OneParen`, and `Period`). +##### \LaTeX{} Example {.unnumbered} -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererFancyOlBegin{% - \markdownRendererFancyOlBeginPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { fancyOlBegin } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { fancyOlBegin } - { 2 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage{verbatim} +\usepackage[hyphens]{url} +\usepackage[fencedCode]{markdown} +\markdownSetup{ + renderers = { + interblockSeparator = { + \def\markdownRendererInterblockSeparator{% + \par + \def\markdownRendererInterblockSeparator{% + \def\markdownRendererInterblockSeparator{% + \par + }% + }% + }% + }, + inputVerbatim = { + is contained in file \url{#1}:% + \verbatiminput{#1}% + }, + inputFencedCode = { + in #2 \markdownRendererInputVerbatim{#1}% + }, + }, +} +\begin{document} +\begin{markdown} +The following code -The \mdef{markdownRendererFancyOlBeginTight} macro represents the beginning of -a fancy ordered list that contains no item with several paragraphs of text (the -list is tight). This macro will only be produced, when the \Opt{fancyLists} -and \Opt{tightLists} options are enabled. The macro receives two arguments: the -style of the list item labels, and the style of delimiters between list -item labels and texts. See the \mref{markdownRendererFancyOlBegin} macro for -the valid style values. + def foo(bar): + if len(bar) <= 1: + return bar[0] + elif len(bar) == 2: + return sorted(bar) + else: + baz = len(bar) // 2 + return foo(bar[baz:], bar[:baz]) + +The following code + +~~~ Python +>>> foo([4, 2, 1, 3]) +[1, 2, 3, 4] +~~~~~~~~~~ +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text except for the filename, which may differ: + +> The following code is contained in file +> `./_markdown_document/882453149edcf288976647f6fe147ada.verbatim`: +> ``` py +> def foo(bar): +> if len(bar) <= 1: +> return bar[:1] +> elif len(bar) == 2: +> return sorted(bar) +> else: +> baz = bar[len(bar) // 2] +> return ( +> foo([qux for qux in bar if qux < baz]) + [baz] + +> foo([qux for qux in bar if qux > baz]) +> ) +> `````` +> The following code in Python contained in file +> `./_markdown_document/cf2a96e2120cef5b1fae5fea36fcc27b.verbatim`: +> ``` py +> >>> foo([4, 2, 1, 3]) +> [1, 2, 3, 4] +> `````` -% \end{markdown} -% -% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererFancyOlBeginTight{% - \markdownRendererFancyOlBeginTightPrototype}% +\def\markdownRendererInputFencedCode{% + \markdownRendererInputFencedCodePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { fancyOlBeginTight } + { inputFencedCode } \prop_gput:Nnn \g_@@_renderer_arities_prop - { fancyOlBeginTight } + { inputFencedCode } { 2 } \ExplSyntaxOff % \end{macrocode} @@ -11842,234 +10877,142 @@ the valid style values. %</tex> %<*manual-tokens> % \fi -% % \begin{markdown} -The \mdef{markdownRendererOlItem} macro represents an item in an ordered list. -This macro will only be produced, when the \Opt{startNumber} option is -disabled and the \Opt{fancyLists} option is disabled. The macro receives no -arguments. +#### Code Span Renderer +The \mdef{markdownRendererCodeSpan} macro represents inline code span in the +input text. It receives a single argument that corresponds to the inline +code span. % \end{markdown} % % \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererOlItem{% - \markdownRendererOlItemPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { olItem } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { olItem } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} -The \mdef{markdownRendererOlItemEnd} macro represents the end of an item in -an ordered list. This macro will only be produced, when the \Opt{fancyLists} -option is disabled. The macro receives no arguments. +##### Plain \TeX{} Example {.unnumbered} -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererOlItemEnd{% - \markdownRendererOlItemEndPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { olItemEnd } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { olItemEnd } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts -The \mdef{markdownRendererOlItemWithNumber} macro represents an item in an -ordered list. This macro will only be produced, when the \Opt{startNumber} -option is enabled and the \Opt{fancyLists} option is disabled. The macro -receives a single numeric argument that corresponds to the item number. +\def\markdownRendererCodeSpan#1{#1} -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererOlItemWithNumber{% - \markdownRendererOlItemWithNumberPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { olItemWithNumber } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { olItemWithNumber } - { 1 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +\markdownBegin +`$\sqrt{-1}$ *equals* $i$` -The \mdef{markdownRendererFancyOlItem} macro represents an item in a fancy -ordered list. This macro will only be produced, when the \Opt{startNumber} -option is disabled and the \Opt{fancyLists} option is enabled. The macro receives -no arguments. +$\sqrt{-1}$ *equals* $i$ +\markdownEnd -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererFancyOlItem{% - \markdownRendererFancyOlItemPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { fancyOlItem } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { fancyOlItem } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +\def\markdownOptionHybrid{true} +\markdownBegin +$\sqrt{-1}$ *equals* $i$ +\markdownEnd -The \mdef{markdownRendererFancyOlItemEnd} macro represents the end of an item in -a fancy ordered list. This macro will only be produced, when the \Opt{fancyLists} -option is enabled. The macro receives no arguments. +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererFancyOlItemEnd{% - \markdownRendererFancyOlItemEndPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { fancyOlItemEnd } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { fancyOlItemEnd } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +> \$\\sqrt{-1}\$ \*equals\* \$i\$. +> +> \$\\sqrt{-1}\$ *equals* \$i\$. +> +> √-̅1̅ *equals* $i$. -The \mdef{markdownRendererFancyOlItemWithNumber} macro represents an item in a -fancy ordered list. This macro will only be produced, when the \Opt{startNumber} -and \Opt{fancyLists} options are enabled. The macro receives a single numeric -argument that corresponds to the item number. +##### \LaTeX{} Example {.unnumbered} -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererFancyOlItemWithNumber{% - \markdownRendererFancyOlItemWithNumberPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { fancyOlItemWithNumber } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { fancyOlItemWithNumber } - { 1 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[smartEllipses]{markdown} +\markdownSetup{ + renderers = { + codeSpan = {#1}, + }, +} +\begin{document} -The \mdef{markdownRendererOlEnd} macro represents the end of an ordered list -that contains an item with several paragraphs of text (the list is not -tight). This macro will only be produced, when the \Opt{fancyLists} option is -disabled. The macro receives no arguments. +\begin{markdown} +`$\sqrt{-1}$ *equals* $i$` + +$\sqrt{-1}$ *equals* $i$ +\end{markdown} + +\begin{markdown*}{hybrid} +$\sqrt{-1}$ *equals* $i$ +\end{markdown*} + +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \$\\sqrt{-1}\$ \*equals\* \$i\$. +> +> \$\\sqrt{-1}\$ *equals* \$i\$. +> +> √-̅1̅ *equals* $i$. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownRendererCodeSpan#1{#1} +\starttext + +\startmarkdown +`$\sqrt{-1}$ *equals* $i$` + +$\sqrt{-1}$ *equals* $i$ +\stopmarkdown + +\setupmarkdown[hybrid = yes] +\startmarkdown +$\sqrt{-1}$ *equals* $i$ +\stopmarkdown + +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \$\\sqrt{-1}\$ \*equals\* \$i\$. +> +> \$\\sqrt{-1}\$ *equals* \$i\$. +> +> √-̅1̅ *equals* $i$. -% \end{markdown} -% -% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererOlEnd{% - \markdownRendererOlEndPrototype}% +\def\markdownRendererCodeSpan{% + \markdownRendererCodeSpanPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { olEnd } + { codeSpan } \prop_gput:Nnn \g_@@_renderer_arities_prop - { olEnd } - { 0 } + { codeSpan } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -12081,11 +11024,13 @@ disabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererOlEndTight} macro represents the end of an ordered -list that contains no item with several paragraphs of text (the list is -tight). This macro will only be produced, when the \Opt{tightLists} option is -enabled and the \Opt{fancyLists} option is disabled. The macro receives no -arguments. +#### Content Block Renderers {#texcontentblockrenderers} + +The \mdef{markdownRendererContentBlock} macro represents an iA\,Writer content +block. It receives four arguments: the local file or online image filename +extension cast to the lower case, the fully escaped \acro{uri} that can be +directly typeset, the raw \acro{uri} that can be used outside typesetting, +and the title of the content block. % \end{markdown} % @@ -12095,16 +11040,16 @@ arguments. % \fi % % \begin{macrocode} -\def\markdownRendererOlEndTight{% - \markdownRendererOlEndTightPrototype}% +\def\markdownRendererContentBlock{% + \markdownRendererContentBlockPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { olEndTight } + { contentBlock } \prop_gput:Nnn \g_@@_renderer_arities_prop - { olEndTight } - { 0 } + { contentBlock } + { 4 } \ExplSyntaxOff % \end{macrocode} % \par @@ -12116,10 +11061,9 @@ arguments. % % \begin{markdown} -The \mdef{markdownRendererFancyOlEnd} macro represents the end of a fancy -ordered list that contains an item with several paragraphs of text (the list -is not tight). This macro will only be produced, when the \Opt{fancyLists} -option is enabled. The macro receives no arguments. +The \mdef{markdownRendererContentBlockOnlineImage} macro represents an +iA\,Writer online image content block. The macro receives the same arguments +as \mref{markdownRendererContentBlock}. % \end{markdown} % @@ -12129,16 +11073,16 @@ option is enabled. The macro receives no arguments. % \fi % % \begin{macrocode} -\def\markdownRendererFancyOlEnd{% - \markdownRendererFancyOlEndPrototype}% +\def\markdownRendererContentBlockOnlineImage{% + \markdownRendererContentBlockOnlineImagePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { fancyOlEnd } + { contentBlockOnlineImage } \prop_gput:Nnn \g_@@_renderer_arities_prop - { fancyOlEnd } - { 0 } + { contentBlockOnlineImage } + { 4 } \ExplSyntaxOff % \end{macrocode} % \par @@ -12150,14 +11094,33 @@ option is enabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererFancyOlEndTight} macro represents the end of a -fancy ordered list that contains no item with several paragraphs of text (the -list is tight). This macro will only be produced, when the \Opt{fancyLists} -and \Opt{tightLists} options are enabled. The macro receives no arguments. +The \mdef{markdownRendererContentBlockCode} macro represents an iA\,Writer +content block that was recognized as a file in a known programming language +by its filename extension $s$. If any `markdown-languages.json` file found +by \pkg{kpathsea}^[Filenames other than `markdown-languages.json` may +be specified using the `contentBlocksLanguageMap` Lua option.] contains a +record $(k, v)$, then a non-online-image content block with the filename +extension $s, s$`:lower()`${}=k$ is considered to be in a known programming +language $v$. +The macro receives five arguments: the local file name extension $s$ cast to +the lower case, the language $v$, the fully escaped \acro{uri} that can be +directly typeset, the raw \acro{uri} that can be used outside typesetting, +and the title of the content block. +Note that you will need to place place a `markdown-languages.json` file +inside your working directory or inside your local \TeX{} directory +structure. In this file, you will define a mapping between filename +extensions and the language names recognized by your favorite syntax +highlighter; there may exist other creative uses beside syntax highlighting. +% The `Languages.json` file provided by @sotkov17 is a good starting point. % \end{markdown} % % \iffalse +[The `Languages.json` file provided by Anton Sotkov][sotkov17] is a good +starting point. + + [sotkov17]: https://github.com/iainc/Markdown-Content-Blocks + (File transclusion syntax for Markdown) ##### Plain \TeX{} Example {.unnumbered} @@ -12165,66 +11128,31 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownOptionTightLists{true} -\def\markdownOptionStartNumber{true} - -\def\markdownRendererInterblockSeparator{} -\def\markdownRendererOlBeginTight{ (} -\def\markdownRendererOlItemWithNumber#1{% - \ifnum #1=1\relax - the first - \else - \ifnum #1=2\relax - , the second - \else - , and the third - \fi - \fi +\def\markdownOptionContentBlocks{true} +\def\markdownRendererContentBlock#1#2#3#4{% + This is {\tt #2}, #4. } -\def\markdownRendererOlItemEnd{} -\def\markdownRendererOlEndTight{).} - -\markdownBegin -This is a tight list - -1. item -2. item -3. item -\markdownEnd - -\def\markdownRendererInterblockSeparator{% - :\par - \def\markdownRendererInterblockSeparator{\par}% +\def\markdownRendererContentBlockOnlineImage#1#2#3#4{% + This is the image {\tt #2}, #4. } -\def\markdownRendererOlBegin{} -\def\markdownRendererOlItemWithNumber#1{% - #1.\kern 0.5em% - This is the - \ifnum #1=1\relax - first - \else - \ifnum #1=2\relax - second - \else - third - \fi - \fi +\def\markdownRendererContentBlockCode#1#2#3#4#5{% + This is the #2 (\uppercase{#1}) document {\tt #3}, #5. } -\def\markdownRendererOlItemEnd{.\par} -\def\markdownRendererOlEnd{} - \markdownBegin -This is a loose list - -1. item - -2. item - -3. item +/document.tex (the document that we are currently typesetting) +/markdown-languages.json (the mapping between filename extensions + and programming language names) +https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) \markdownEnd - \bye ``````` +Create also a text document named `markdown-languages.json` with the following +content: +``` js +{ + "json": "JavaScript Object Notation", +} +`````` Next, invoke LuaTeX from the terminal: ``` sh luatex document.tex @@ -12232,15 +11160,14 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is a tight list (the first item, the second item, and the third item). +> This is `document.tex`, the document that we are currently typesetting. > -> This is a loose list: -> -> 1. This is the first item. -> -> 2. This is the second item. -> -> 3. This is the third item. +> This is the JavaScript Object Notation (JSON) document +> `markdown-languages.json`, the mapping between filename extensions and +> programming language names. +> +> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of +> TUGboat. ##### \LaTeX{} Example {.unnumbered} @@ -12248,67 +11175,28 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[tightLists, startNumber]{markdown} -\begin{document} - -\begin{markdown*}{ - renderers = { - interblockSeparator = {}, - olBeginTight = { (}, - olItemWithNumber = {% - \ifnum #1=1\relax - the first - \else - \ifnum #1=2\relax - , the second - \else - , and the third - \fi - \fi - }, - olItemEnd = {}, - olEndTight = {).}, - }, +\begin{filecontents}[overwrite,nosearch,noheader]{markdown-languages.json} +{ + "json": "JavaScript Object Notation", } -This is a tight list - -1. item -2. item -3. item -\end{markdown*} - -\begin{markdown*}{ +\end{filecontents} +\usepackage[contentBlocks]{markdown} +\markdownSetup{ renderers = { - interblockSeparator = {% - :\par - \def\markdownRendererInterblockSeparator{\par}% - }, - olBeginTight = {\begin{enumerate}}, - olItemWithNumber = {% - \item This is the - \ifnum #1=1\relax - first - \else - \ifnum #1=2\relax - second - \else - third - \fi - \fi + contentBlock = {This is \texttt{#2}, #4.}, + contentBlockOnlineImage = {This is the image \texttt{#2}, #4.}, + contentBlockCode = {% + This is the #2 (\MakeUppercase{#1}) document \texttt{#3}, #5. }, - olItemEnd = {.}, - olEnd = {\end{enumerate}}, - }, + }, } -This is a loose list - -1. item - -2. item - -3. item -\end{markdown*} - +\begin{document} +\begin{markdown} +/document.tex (the document that we are currently typesetting) +/markdown-languages.json (the mapping between filename extensions + and programming language names) +https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) +\end{markdown} \end{document} ``````` Next, invoke LuaTeX from the terminal: @@ -12318,15 +11206,14 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is a tight list (the first item, the second item, and the third item). +> This is `document.tex`, the document that we are currently typesetting. > -> This is a loose list: -> -> 1. This is the first item. -> -> 2. This is the second item. -> -> 3. This is the third item. +> This is the JavaScript Object Notation (JSON) document +> `markdown-languages.json`, the mapping between filename extensions and +> programming language names. +> +> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of +> TUGboat. ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -12334,70 +11221,32 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\setupmarkdown - [ - tightLists = yes, - startNumber = yes, - ] -\starttext - -\def\markdownRendererInterblockSeparator{} -\def\markdownRendererOlBeginTight{ (} -\def\markdownRendererOlItemWithNumber#1{% - \ifnum #1=1\relax - the first - \else - \ifnum #1=2\relax - , the second - \else - , and the third - \fi - \fi +\setupmarkdown[contentBlocks = yes] +\def\markdownRendererContentBlock#1#2#3#4{% + This is {\tt #2}, #4. } -\def\markdownRendererOlItemEnd{} -\def\markdownRendererOlEndTight{).} - -\startmarkdown -This is a tight list - -1. item -2. item -3. item -\stopmarkdown - -\def\markdownRendererInterblockSeparator{% - :\par - \def\markdownRendererInterblockSeparator{\par}% +\def\markdownRendererContentBlockOnlineImage#1#2#3#4{% + This is the image {\tt #2}, #4. } -\def\markdownRendererOlBegin{\startitemize} -\def\markdownRendererOlItemWithNumber#1{% - \sym{#1.} - This is the - \ifnum #1=1\relax - first - \else - \ifnum #1=2\relax - second - \else - third - \fi - \fi +\def\markdownRendererContentBlockCode#1#2#3#4#5{% + This is the #2 (\uppercase{#1}) document {\tt #3}, #5. } -\def\markdownRendererOlItemEnd{.\par} -\def\markdownRendererOlEnd{\stopitemize} - +\starttext \startmarkdown -This is a loose list - -1. item - -2. item - -3. item +/document.tex (the document that we are currently typesetting) +/markdown-languages.json (the mapping between filename extensions + and programming language names) +https://tug.org/tugboat/noword.jpg (the logotype of TUGboat) \stopmarkdown - \stoptext ``````` +Create also a text document named `markdown-languages.json` with the following +content: +``` js +{ + "json": "JavaScript Object Notation", +} +`````` Next, invoke LuaTeX from the terminal: ``` sh context document.tex @@ -12405,31 +11254,30 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is a tight list (the first item, the second item, and the third item). +> This is `document.tex`, the document that we are currently typesetting. > -> This is a loose list: -> -> 1. This is the first item. -> -> 2. This is the second item. -> -> 3. This is the third item. +> This is the JavaScript Object Notation (JSON) document +> `markdown-languages.json`, the mapping between filename extensions and +> programming language names. +> +> This is the image `https://tug.org/tugboat/noword.jpg`, the logotype of +> TUGboat. %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererFancyOlEndTight{% - \markdownRendererFancyOlEndTightPrototype}% +\def\markdownRendererContentBlockCode{% + \markdownRendererContentBlockCodePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { fancyOlEndTight } + { contentBlockCode } \prop_gput:Nnn \g_@@_renderer_arities_prop - { fancyOlEndTight } - { 0 } + { contentBlockCode } + { 5 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13045,10 +11893,10 @@ following text: % % \begin{markdown} -#### Emphasis Renderers -The \mdef{markdownRendererEmphasis} macro represents an emphasized span of -text. The macro receives a single argument that corresponds to the emphasized -span of text. +#### Ellipsis Renderer +The \mdef{markdownRendererEllipsis} macro replaces any occurance of ASCII +ellipses in the input text. This macro will only be produced, when the +\Opt{smartEllipses} option is enabled. The macro receives no arguments. % \end{markdown} % @@ -13060,12 +11908,10 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownRendererEmphasis#1{{\it#1}} -\def\markdownRendererStrongEmphasis#1{{\bf#1}} +\def\markdownOptionSmartEllipses{true} +\def\markdownRendererEllipsis{{\it SHAZAM}!} \markdownBegin -This is *emphasis*. - -This is **strong emphasis**. +The secret word is ... \markdownEnd \bye ``````` @@ -13076,9 +11922,7 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is *emphasis*. -> -> This is **strong emphasis**. +> The secret word is *SHAZAM*! ##### \LaTeX{} Example {.unnumbered} @@ -13086,18 +11930,15 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage{markdown} +\usepackage[smartEllipses]{markdown} \markdownSetup{ renderers = { - emphasis = {\emph{#1}}, - strongEmphasis = {\textbf{#1}}, + ellipsis = \emph{SHAZAM}!, }, } \begin{document} \begin{markdown} -This is *emphasis*. - -This is **strong emphasis**. +The secret word is ... \end{markdown} \end{document} ``````` @@ -13108,9 +11949,7 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is *emphasis*. -> -> This is **strong emphasis**. +> The secret word is *SHAZAM*! ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -13118,13 +11957,11 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\def\markdownRendererEmphasis#1{\emph{#1}} -\def\markdownRendererStrongEmphasis#1{\bold{#1}} +\setupmarkdown[smartEllipses = yes] +\def\markdownRendererEllipsis{\emph{SHAZAM}!} \starttext \startmarkdown -This is *emphasis*. - -This is **strong emphasis**. +The secret word is ... \stopmarkdown \stoptext ``````` @@ -13135,90 +11972,26 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is *emphasis*. +> Hello *world*! > -> This is **strong emphasis**. - -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererEmphasis{% - \markdownRendererEmphasisPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { emphasis } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { emphasis } - { 1 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -The \mdef{markdownRendererStrongEmphasis} macro represents a strongly -emphasized span of text. The macro receives a single argument that -corresponds to the emphasized span of text. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererStrongEmphasis{% - \markdownRendererStrongEmphasisPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { strongEmphasis } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { strongEmphasis } - { 1 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -#### Block Quote Renderers -The \mdef{markdownRendererBlockQuoteBegin} macro represents the beginning of -a block quote. The macro receives no arguments. +> *(The end of a block)* +> +> _Foo_ bar! -% \end{markdown} -% -% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererBlockQuoteBegin{% - \markdownRendererBlockQuoteBeginPrototype}% +\def\markdownRendererEllipsis{% + \markdownRendererEllipsisPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { blockQuoteBegin } + { ellipsis } \prop_gput:Nnn \g_@@_renderer_arities_prop - { blockQuoteBegin } + { ellipsis } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -13231,8 +12004,10 @@ a block quote. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block -quote. The macro receives no arguments. +#### Emphasis Renderers +The \mdef{markdownRendererEmphasis} macro represents an emphasized span of +text. The macro receives a single argument that corresponds to the emphasized +span of text. % \end{markdown} % @@ -13244,24 +12019,12 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownRendererBlockQuoteBegin{% - \begingroup - \vskip\parindent - \leftskip=2\parindent - \parindent=0pt -} -\def\markdownRendererBlockQuoteEnd{% - \par - \vskip\parindent - \endgroup -} +\def\markdownRendererEmphasis#1{{\it#1}} +\def\markdownRendererStrongEmphasis#1{{\bf#1}} \markdownBegin -A quote from William Shakespeare's King Lear: +This is *emphasis*. -> This is the excellent foppery of the world that when we are -> sick in fortune---often the surfeit of our own behavior---we -> make guilty of our disasters the sun, the moon, and the -> stars [...] +This is **strong emphasis**. \markdownEnd \bye ``````` @@ -13272,12 +12035,9 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> A quote from William Shakespeare's King Lear: +> This is *emphasis*. > -> > This is the excellent foppery of the world that when we are -> > sick in fortune—often the surfeit of our own behavior—we -> > make guilty of our disasters the sun, the moon, and the -> > stars [...] +> This is **strong emphasis**. ##### \LaTeX{} Example {.unnumbered} @@ -13288,18 +12048,15 @@ following content: \usepackage{markdown} \markdownSetup{ renderers = { - blockQuoteBegin = {\begin{quote}}, - blockQuoteEnd = {\end{quote}}, + emphasis = {\emph{#1}}, + strongEmphasis = {\textbf{#1}}, }, } \begin{document} \begin{markdown} -A quote from William Shakespeare's King Lear: +This is *emphasis*. -> This is the excellent foppery of the world that when we are -> sick in fortune---often the surfeit of our own behavior---we -> make guilty of our disasters the sun, the moon, and the -> stars [...] +This is **strong emphasis**. \end{markdown} \end{document} ``````` @@ -13310,12 +12067,9 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> A quote from William Shakespeare's King Lear: +> This is *emphasis*. > -> > This is the excellent foppery of the world that when we are -> > sick in fortune—often the surfeit of our own behavior—we -> > make guilty of our disasters the sun, the moon, and the -> > stars [...] +> This is **strong emphasis**. ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -13323,16 +12077,13 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\def\markdownRendererBlockQuoteBegin{\startquotation} -\def\markdownRendererBlockQuoteEnd{\stopquotation} +\def\markdownRendererEmphasis#1{\emph{#1}} +\def\markdownRendererStrongEmphasis#1{\bold{#1}} \starttext \startmarkdown -A quote from William Shakespeare's King Lear: +This is *emphasis*. -> This is the excellent foppery of the world that when we are -> sick in fortune---often the surfeit of our own behavior---we -> make guilty of our disasters the sun, the moon, and the -> stars [...] +This is **strong emphasis**. \stopmarkdown \stoptext ``````` @@ -13343,28 +12094,25 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> A quote from William Shakespeare's King Lear: +> This is *emphasis*. > -> > This is the excellent foppery of the world that when we are -> > sick in fortune—often the surfeit of our own behavior—we -> > make guilty of our disasters the sun, the moon, and the -> > stars [...] +> This is **strong emphasis**. %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererBlockQuoteEnd{% - \markdownRendererBlockQuoteEndPrototype}% +\def\markdownRendererEmphasis{% + \markdownRendererEmphasisPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { blockQuoteEnd } + { emphasis } \prop_gput:Nnn \g_@@_renderer_arities_prop - { blockQuoteEnd } - { 0 } + { emphasis } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13376,10 +12124,9 @@ following text: % % \begin{markdown} -#### Code Block Renderers -The \mdef{markdownRendererInputVerbatim} macro represents a code -block. The macro receives a single argument that corresponds to the -filename of a file contaning the code block contents. +The \mdef{markdownRendererStrongEmphasis} macro represents a strongly +emphasized span of text. The macro receives a single argument that +corresponds to the emphasized span of text. % \end{markdown} % @@ -13389,15 +12136,15 @@ filename of a file contaning the code block contents. % \fi % % \begin{macrocode} -\def\markdownRendererInputVerbatim{% - \markdownRendererInputVerbatimPrototype}% +\def\markdownRendererStrongEmphasis{% + \markdownRendererStrongEmphasisPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inputVerbatim } + { strongEmphasis } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inputVerbatim } + { strongEmphasis } { 1 } \ExplSyntaxOff % \end{macrocode} @@ -13410,10 +12157,14 @@ filename of a file contaning the code block contents. % % \begin{markdown} -The \mdef{markdownRendererInputFencedCode} macro represents a fenced code -block. This macro will only be produced, when the \Opt{fencedCode} option is -enabled. The macro receives two arguments that correspond to the filename of -a file contaning the code block contents and to the code fence infostring. +#### Fenced Div Context Renderers +The following macros are only produced, when the \Opt{fencedDiv} option is +enabled. + +The \mdef{markdownRendererFencedDivAttributeContextBegin} and +\mdef{markdownRendererFencedDivAttributeContextEnd} macros represent the beginning +and the end of a div in which the attributes of the div apply. The macros +receive no arguments. % \end{markdown} % @@ -13425,49 +12176,42 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage{verbatim} -\usepackage[hyphens]{url} -\usepackage[fencedCode]{markdown} +\usepackage[fencedDiv]{markdown} \markdownSetup{ renderers = { - interblockSeparator = { - \def\markdownRendererInterblockSeparator{% - \par - \def\markdownRendererInterblockSeparator{% - \def\markdownRendererInterblockSeparator{% - \par - }% - }% - }% - }, - inputVerbatim = { - is contained in file \url{#1}:% - \verbatiminput{#1}% + fencedDivAttributeContextBegin = {% + \par + \emph{(The beginning of a fenced div attribute context)} + \par }, - inputFencedCode = { - in #2 \markdownRendererInputVerbatim{#1}% + fencedDivAttributeContextEnd = {% + \par + \emph{(The end of a fenced div attribute context)} + \par }, }, } \begin{document} \begin{markdown} -The following code - def foo(bar): - if len(bar) <= 1: - return bar[0] - elif len(bar) == 2: - return sorted(bar) - else: - baz = len(bar) // 2 - return foo(bar[baz:], bar[:baz]) +::: {key=value} -The following code +foo + +:::: {#identifier} + +bar + +:::: + +::: + +::: {.class_name} + +baz + +::: -~~~ Python ->>> foo([4, 2, 1, 3]) -[1, 2, 3, 4] -~~~~~~~~~~ \end{markdown} \end{document} ``````` @@ -13476,78 +12220,51 @@ Next, invoke LuaTeX from the terminal: lualatex document.tex `````` A PDF document named `document.pdf` should be produced and contain the -following text except for the filename, which may differ: +following text: -> The following code is contained in file -> `./_markdown_document/882453149edcf288976647f6fe147ada.verbatim`: -> ``` py -> def foo(bar): -> if len(bar) <= 1: -> return bar[:1] -> elif len(bar) == 2: -> return sorted(bar) -> else: -> baz = bar[len(bar) // 2] -> return ( -> foo([qux for qux in bar if qux < baz]) + [baz] + -> foo([qux for qux in bar if qux > baz]) -> ) -> `````` -> The following code in Python contained in file -> `./_markdown_document/cf2a96e2120cef5b1fae5fea36fcc27b.verbatim`: -> ``` py -> >>> foo([4, 2, 1, 3]) -> [1, 2, 3, 4] -> `````` +> *(The beginning of a fenced div attribute context)* +> +> foo +> +> *(The beginning of a fenced div attribute context)* +> +> bar +> +> *(The end of a fenced div attribute context)* +> +> *(The end of a fenced div attribute context)* +> +> *(The beginning of a fenced div attribute context)* +> +> baz +> +> *(The end of a fenced div attribute context)* %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererInputFencedCode{% - \markdownRendererInputFencedCodePrototype}% +\def\markdownRendererFencedDivAttributeContextBegin{% + \markdownRendererFencedDivAttributeContextBeginPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inputFencedCode } + { fencedDivAttributeContextBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inputFencedCode } - { 2 } + { fencedDivAttributeContextBegin } + { 0 } \ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% \begin{markdown} - -#### YAML Metadata Renderers {#yamlmetadatarenderers} - -The \mdef{markdownRendererJekyllDataBegin} macro represents the beginning of a -\acro{yaml} document. This macro will only be produced when the \Opt{jekyllData} -option is enabled. The macro receives no arguments. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererJekyllDataBegin{% - \markdownRendererJekyllDataBeginPrototype}% +\def\markdownRendererFencedDivAttributeContextEnd{% + \markdownRendererFencedDivAttributeContextEndPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataBegin } + { fencedDivAttributeContextEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataBegin } + { fencedDivAttributeContextEnd } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -13560,95 +12277,98 @@ option is enabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataEnd} macro represents the end of a -\acro{yaml} document. This macro will only be produced when the -\Opt{jekyllData} option is enabled. The macro receives no arguments. +#### Header Attribute Context Renderers +The following macros are only produced, when the \Opt{headerAttributes} option +is enabled. + +The \mdef{markdownRendererHeaderAttributeContextBegin} and +\mdef{markdownRendererHeaderAttributeContextEnd} macros represent the beginning +and the end of a section in which the attributes of a heading apply. The macros +receive no arguments. % \end{markdown} % % \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererJekyllDataEnd{% - \markdownRendererJekyllDataEndPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { jekyllDataEnd } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { jekyllDataEnd } - { 0 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} -The \mdef{markdownRendererJekyllDataMappingBegin} macro represents the -beginning of a mapping in a \acro{yaml} document. This macro will only be -produced when the \Opt{jekyllData} option is enabled. The macro receives two -arguments: the scalar key in the parent structure, cast to a string following -\acro{yaml} serialization rules, and the number of items in the mapping. +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[headerAttributes]{markdown} +\markdownSetup{ + renderers = { + headerAttributeContextBegin = {% + \par + \emph{(The beginning of a header attribute context)} + \par + }, + headerAttributeContextEnd = {% + \par + \emph{(The end of a header attribute context)} + \par + }, + }, +} +\begin{document} +\begin{markdown} + +# First top-level heading + +## A subheading {#identifier} + +# Second top-level heading {.class_name} + +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> # First top-level heading +> +> *(The beginning of a header attribute context)* +> +> ## A subheading +> +> *(The end of a header attribute context)* +> +> *(The beginning of a header attribute context)* +> +> # Second top-level heading +> +> *(The end of a header attribute context)* -% \end{markdown} -% -% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataMappingBegin{% - \markdownRendererJekyllDataMappingBeginPrototype}% +\def\markdownRendererHeaderAttributeContextBegin{% + \markdownRendererHeaderAttributeContextBeginPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataMappingBegin } + { headerAttributeContextBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataMappingBegin } - { 2 } + { headerAttributeContextBegin } + { 0 } \ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> -% \fi -% -% \begin{markdown} - -The \mdef{markdownRendererJekyllDataMappingEnd} macro represents the -end of a mapping in a \acro{yaml} document. This macro will only be produced -when the \Opt{jekyllData} option is enabled. The macro receives no arguments. - -% \end{markdown} -% -% \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererJekyllDataMappingEnd{% - \markdownRendererJekyllDataMappingEndPrototype}% +\def\markdownRendererHeaderAttributeContextEnd{% + \markdownRendererHeaderAttributeContextEndPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataMappingEnd } + { headerAttributeContextEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataMappingEnd } + { headerAttributeContextEnd } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -13661,11 +12381,9 @@ when the \Opt{jekyllData} option is enabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataSequenceBegin} macro represents the -beginning of a sequence in a \acro{yaml} document. This macro will only be -produced when the \Opt{jekyllData} option is enabled. The macro receives two -arguments: the scalar key in the parent structure, cast to a string following -\acro{yaml} serialization rules, and the number of items in the sequence. +#### Heading Renderers +The \mdef{markdownRendererHeadingOne} macro represents a first level heading. +The macro receives a single argument that corresponds to the heading text. % \end{markdown} % @@ -13675,16 +12393,16 @@ arguments: the scalar key in the parent structure, cast to a string following % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataSequenceBegin{% - \markdownRendererJekyllDataSequenceBeginPrototype}% +\def\markdownRendererHeadingOne{% + \markdownRendererHeadingOnePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataSequenceBegin } + { headingOne } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataSequenceBegin } - { 2 } + { headingOne } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13696,9 +12414,9 @@ arguments: the scalar key in the parent structure, cast to a string following % % \begin{markdown} -The \mdef{markdownRendererJekyllDataSequenceEnd} macro represents the -end of a sequence in a \acro{yaml} document. This macro will only be produced -when the \Opt{jekyllData} option is enabled. The macro receives no arguments. +The \mdef{markdownRendererHeadingTwo} macro represents a second level +heading. The macro receives a single argument that corresponds to the heading +text. % \end{markdown} % @@ -13708,16 +12426,16 @@ when the \Opt{jekyllData} option is enabled. The macro receives no arguments. % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataSequenceEnd{% - \markdownRendererJekyllDataSequenceEndPrototype}% +\def\markdownRendererHeadingTwo{% + \markdownRendererHeadingTwoPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataSequenceEnd } + { headingTwo } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataSequenceEnd } - { 0 } + { headingTwo } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13729,11 +12447,9 @@ when the \Opt{jekyllData} option is enabled. The macro receives no arguments. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataBoolean} macro represents a boolean scalar -value in a \acro{yaml} document. This macro will only be produced when the -\Opt{jekyllData} option is enabled. The macro receives two arguments: the -scalar key in the parent structure, and the scalar value, both cast to a string -following \acro{yaml} serialization rules. +The \mdef{markdownRendererHeadingThree} macro represents a third level +heading. The macro receives a single argument that corresponds to the heading +text. % \end{markdown} % @@ -13743,16 +12459,16 @@ following \acro{yaml} serialization rules. % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataBoolean{% - \markdownRendererJekyllDataBooleanPrototype}% +\def\markdownRendererHeadingThree{% + \markdownRendererHeadingThreePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataBoolean } + { headingThree } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataBoolean } - { 2 } + { headingThree } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13764,11 +12480,9 @@ following \acro{yaml} serialization rules. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataNumber} macro represents a numeric scalar -value in a \acro{yaml} document. This macro will only be produced when the -\Opt{jekyllData} option is enabled. The macro receives two arguments: the -scalar key in the parent structure, and the scalar value, both cast to a string -following \acro{yaml} serialization rules. +The \mdef{markdownRendererHeadingFour} macro represents a fourth level +heading. The macro receives a single argument that corresponds to the heading +text. % \end{markdown} % @@ -13778,16 +12492,16 @@ following \acro{yaml} serialization rules. % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataNumber{% - \markdownRendererJekyllDataNumberPrototype}% +\def\markdownRendererHeadingFour{% + \markdownRendererHeadingFourPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataNumber } + { headingFour } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataNumber } - { 2 } + { headingFour } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13799,11 +12513,9 @@ following \acro{yaml} serialization rules. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataString} macro represents a string scalar -value in a \acro{yaml} document. This macro will only be produced when the -\Opt{jekyllData} option is enabled. The macro receives two arguments: the -scalar key in the parent structure, cast to a string following \acro{yaml} -serialization rules, and the scalar value. +The \mdef{markdownRendererHeadingFive} macro represents a fifth level +heading. The macro receives a single argument that corresponds to the heading +text. % \end{markdown} % @@ -13813,16 +12525,16 @@ serialization rules, and the scalar value. % \fi % % \begin{macrocode} -\def\markdownRendererJekyllDataString{% - \markdownRendererJekyllDataStringPrototype}% +\def\markdownRendererHeadingFive{% + \markdownRendererHeadingFivePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { jekyllDataString } + { headingFive } \prop_gput:Nnn \g_@@_renderer_arities_prop - { jekyllDataString } - { 2 } + { headingFive } + { 1 } \ExplSyntaxOff % \end{macrocode} % \par @@ -13834,41 +12546,13 @@ serialization rules, and the scalar value. % % \begin{markdown} -The \mdef{markdownRendererJekyllDataEmpty} macro represents an empty scalar -value in a \acro{yaml} document. This macro will only be produced when the -\Opt{jekyllData} option is enabled. The macro receives one argument: the -scalar key in the parent structure, cast to a string following \acro{yaml} -serialization rules. +The \mdef{markdownRendererHeadingSix} macro represents a sixth level +heading. The macro receives a single argument that corresponds to the heading +text. -% See also Section <#sec:expl3yamlmetadata> for the description of the -% high-level expl3 interface that you can also use to react to \acro{yaml} -% metadata. -% % \end{markdown} % % \iffalse -%</manual-tokens> -%<*tex> -% \fi -% -% \begin{macrocode} -\def\markdownRendererJekyllDataEmpty{% - \markdownRendererJekyllDataEmptyPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { jekyllDataEmpty } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { jekyllDataEmpty } - { 1 } -\ExplSyntaxOff -% \end{macrocode} -% \par -% -% \iffalse -%</tex> -%<*manual-tokens> ##### Plain \TeX{} Example {.unnumbered} @@ -13876,16 +12560,19 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownOptionJekyllData{true} -\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} -\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} -\def\markdownRendererJekyllDataEnd{% - \name{} is \age{} years old.} +\def\markdownRendererInterblockSeparator{} +\def\markdownRendererHeadingOne{1} +\def\markdownRendererHeadingTwo{2} +\def\markdownRendererHeadingThree{3} +\def\markdownRendererHeadingFour{4} +\def\markdownRendererHeadingFive{5} +\def\markdownRendererHeadingSix{6} \markdownBegin ---- -name: Jane Doe -age: 99 ---- +###### +##### +##### +### +###### \markdownEnd \bye ``````` @@ -13896,7 +12583,7 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> Jane Doe is 99 years old. +> 65536 ##### \LaTeX{} Example {.unnumbered} @@ -13904,23 +12591,26 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[jekyllData]{markdown} +\usepackage{markdown} \markdownSetup{ renderers = { - jekyllDataString = {\gdef\name{#2}}, - jekyllDataNumber = {\gdef\age{#2}}, - jekyllDataEnd = {\name{} is \age{} years old.}, - } + interblockSeparator = {}, + headingOne = 1, + headingTwo = 2, + headingThree = 3, + headingFour = 4, + headingFive = 5, + headingSix = 6, + }, } \begin{document} - \begin{markdown} ---- -name: Jane Doe -age: 99 ---- +###### +##### +##### +### +###### \end{markdown} - \end{document} ``````` Next, invoke LuaTeX from the terminal: @@ -13930,7 +12620,7 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> Jane Doe is 99 years old. +> 65536 ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -13938,20 +12628,21 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\setupmarkdown[jekyllData = yes] -\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} -\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} -\def\markdownRendererJekyllDataEnd{% - \name{} is \age{} years old.} +\def\markdownRendererInterblockSeparator{} +\def\markdownRendererHeadingOne{1} +\def\markdownRendererHeadingTwo{2} +\def\markdownRendererHeadingThree{3} +\def\markdownRendererHeadingFour{4} +\def\markdownRendererHeadingFive{5} +\def\markdownRendererHeadingSix{6} \starttext - \startmarkdown ---- -name: Jane Doe -age: 99 ---- +###### +##### +##### +### +###### \stopmarkdown - \stoptext ``````` Next, invoke LuaTeX from the terminal: @@ -13961,33 +12652,22 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> Jane Doe is 99 years old. - -% \fi -% -% \begin{markdown} - -#### Heading Renderers -The \mdef{markdownRendererHeadingOne} macro represents a first level heading. -The macro receives a single argument that corresponds to the heading text. +> 65536 -% \end{markdown} -% -% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingOne{% - \markdownRendererHeadingOnePrototype}% +\def\markdownRendererHeadingSix{% + \markdownRendererHeadingSixPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingOne } + { headingSix } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingOne } + { headingSix } { 1 } \ExplSyntaxOff % \end{macrocode} @@ -14000,29 +12680,112 @@ The macro receives a single argument that corresponds to the heading text. % % \begin{markdown} -The \mdef{markdownRendererHeadingTwo} macro represents a second level -heading. The macro receives a single argument that corresponds to the heading -text. +#### HTML Comment Renderers + +The \mdef{markdownRendererInlineHtmlComment} macro represents the contents of an +inline \acro{HTML} comment. This macro will only be produced, when the +\Opt{html} option is enabled. The macro receives a single argument that +corresponds to the contents of the \acro{HTML} comment. + +The \mdef{markdownRendererBlockHtmlCommentBegin} and +\mdef{markdownRendererBlockHtmlCommentEnd} macros represent the beginning +and the end of a block \acro{HTML} comment. The macros receive no arguments. % \end{markdown} % % \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[html]{markdown} +\usepackage{marginnote} +\markdownSetup{ + renderers = { + inlineHtmlComment = {\marginnote{#1}}, + blockHtmlCommentBegin = {\begin{quote}}, + blockHtmlCommentEnd = {\end{quote}}, + }, +} +\begin{document} +\begin{markdown} +A useful use of inline HTML comments are side notes. +<!-- Side notes are displayed in the horizontal margins next to the relevant +passages, which makes them *easier for the reader to find* than notes. --> + +We can render block HTML comments as blockquotes: + +<!-- +Here is a block HTML comment with a code example that a programmer might understand: + + foo = bar + baz - 42 +--> +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following body text: + +> A useful use of HTML comments are side notes. +> +> We can render block HTML comments as blockquotes: +> +> > Here is a block HTML comment with a code example that a programmer might +> > understand: +> > +> > foo = bar + baz - 42 + +The horizontal margins should contain the following text: + +> Side notes are displayed in the horizontal margins next to the relevant +> passages, which makes them *easier for the reader to find* than notes. + %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingTwo{% - \markdownRendererHeadingTwoPrototype}% +\def\markdownRendererInlineHtmlComment{% + \markdownRendererInlineHtmlCommentPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingTwo } + { inlineHtmlComment } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingTwo } + { inlineHtmlComment } { 1 } \ExplSyntaxOff +\def\markdownRendererBlockHtmlCommentBegin{% + \markdownRendererBlockHtmlCommentBeginPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { blockHtmlCommentBegin } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { blockHtmlCommentBegin } + { 0 } +\ExplSyntaxOff +\def\markdownRendererBlockHtmlCommentEnd{% + \markdownRendererBlockHtmlCommentEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { blockHtmlCommentEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { blockHtmlCommentEnd } + { 0 } +\ExplSyntaxOff % \end{macrocode} % \par % @@ -14033,27 +12796,82 @@ text. % % \begin{markdown} -The \mdef{markdownRendererHeadingThree} macro represents a third level -heading. The macro receives a single argument that corresponds to the heading -text. +#### HTML Tag and Element Renderers + +The \mdef{markdownRendererInlineHtmlTag} macro represents an opening, closing, +or empty inline \acro{HTML} tag. This macro will only be produced, when the +\Opt{html} option is enabled. The macro receives a single argument that +corresponds to the contents of the \acro{HTML} tag. + +The \mdef{markdownRendererInputBlockHtmlElement} macro represents a block +\acro{HTML} element. This macro will only be produced, when the \Opt{html} +option is enabled. The macro receives a single argument that filename of a file +containing the contents of the \acro{HTML} element. % \end{markdown} % % \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[html]{markdown} +\usepackage{marginnote} +\usepackage{verbatim} +\markdownSetup{ + renderers = { + inlineHtmlTag = {\textbf{#1}}, + inputBlockHtmlElement = {\verbatiminput{#1}}, + }, +} +\begin{document} +\begin{markdown} +<b>_Hello,_ world!</b><br/> + +<div>_Hello,_ world!</div> +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following body text: + +> **<b>**_Hello,_ world!**</b><br/>** +> +> <div>_Hello,_ world!</div> + %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingThree{% - \markdownRendererHeadingThreePrototype}% +\def\markdownRendererInlineHtmlTag{% + \markdownRendererInlineHtmlTagPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingThree } + { inlineHtmlTag } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingThree } + { inlineHtmlTag } + { 1 } +\ExplSyntaxOff +\def\markdownRendererInputBlockHtmlElement{% + \markdownRendererInputBlockHtmlElementPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { inputBlockHtmlElement } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { inputBlockHtmlElement } { 1 } \ExplSyntaxOff % \end{macrocode} @@ -14066,28 +12884,85 @@ text. % % \begin{markdown} -The \mdef{markdownRendererHeadingFour} macro represents a fourth level -heading. The macro receives a single argument that corresponds to the heading -text. +#### Image Renderer +The \mdef{markdownRendererImage} macro represents an image. It receives +four arguments: the label, the fully escaped \acro{uri} that can be directly +typeset, the raw \acro{uri} that can be used outside typesetting, and the +title of the link. % \end{markdown} % % \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage{markdown} +\begingroup +\catcode`\@=11 +\catcode`\%=12 +\catcode`\^^A=14 +\global\def\markdownRendererImage#1#2#3#4{^^A + \immediate\write18{^^A +``` +``` sh + if printf '%s' "#3" | grep -q ^http; then + OUTPUT="$(printf '%s' "#3" | md5sum | cut -d' ' -f1).^^A + $(printf '%s' "#3" | sed 's/.*[.]//')"; + if ! [ -e "$OUTPUT" ]; then + wget -O "$OUTPUT" '#3' || rm "$OUTPUT"; + convert "$OUTPUT" png:"$OUTPUT"; + fi; + printf '%s%%' "$OUTPUT" > \jobname.fetched; + else + printf '%s%%' "#3" > \jobname.fetched; + fi^^A +``` +``` tex + }^^A + {^^A + \everyeof={\noexpand}^^A + \edef\filename{\@@input"\jobname.fetched" }^^A + \includegraphics[width=\textwidth]{\filename}^^A + }^^A +} +\endgroup +\begin{document} +\begin{markdown} +![TUGboat](https://tug.org/tugboat/noword.jpg) +\end{markdown} +\end{document} +`````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex --shell-escape document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following content. This assumes that you use a Unix-like operating system with +Bourne or Bourne again shell as the default shell of the current user. It also +assumes that the `md5sum`, `wget`, and `convert` binaries are installed and +that the \TeX{} engine has shell access. + +> ![TUGboat](https://tug.org/tugboat/noword.jpg "The Communications of the TeX Users Group") + %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingFour{% - \markdownRendererHeadingFourPrototype}% +\def\markdownRendererImage{% + \markdownRendererImagePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingFour } + { image } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingFour } - { 1 } + { image } + { 4 } \ExplSyntaxOff % \end{macrocode} % \par @@ -14099,28 +12974,129 @@ text. % % \begin{markdown} -The \mdef{markdownRendererHeadingFive} macro represents a fifth level -heading. The macro receives a single argument that corresponds to the heading -text. +#### Interblock Separator Renderer +The \mdef{markdownRendererInterblockSeparator} macro represents a separator +between two markdown block elements. The macro receives no arguments. % \end{markdown} % % \iffalse + +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownRendererInterblockSeparator{% + \par + {\it(The end of a block)}% + \par +} +\markdownBegin +Hello *world*! + +_Foo_ bar! +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Hello *world*! +> +> *(The end of a block)* +> +> _Foo_ bar! + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage{markdown} +\markdownSetup{ + renderers = { + interblockSeparator = {% + \par + \emph{(The end of a block)}% + \par + }, + }, +} +\begin{document} +\begin{markdown} +Hello *world*! + +_Foo_ bar! +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Hello *world*! +> +> *(The end of a block)* +> +> _Foo_ bar! + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownRendererInterblockSeparator{% + \par + \emph{(The end of a block)}% + \par +} +\starttext +\startmarkdown +Hello *world*! + +_Foo_ bar! +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Hello *world*! +> +> *(The end of a block)* +> +> _Foo_ bar! + %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingFive{% - \markdownRendererHeadingFivePrototype}% +\def\markdownRendererInterblockSeparator{% + \markdownRendererInterblockSeparatorPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingFive } + { interblockSeparator } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingFive } - { 1 } + { interblockSeparator } + { 0 } \ExplSyntaxOff % \end{macrocode} % \par @@ -14132,9 +13108,9 @@ text. % % \begin{markdown} -The \mdef{markdownRendererHeadingSix} macro represents a sixth level -heading. The macro receives a single argument that corresponds to the heading -text. +#### Line Break Renderer +The \mdef{markdownRendererLineBreak} macro represents a forced line break. +The macro receives no arguments. % \end{markdown} % @@ -14146,22 +13122,22 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownRendererInterblockSeparator{} -\def\markdownRendererHeadingOne{1} -\def\markdownRendererHeadingTwo{2} -\def\markdownRendererHeadingThree{3} -\def\markdownRendererHeadingFour{4} -\def\markdownRendererHeadingFive{5} -\def\markdownRendererHeadingSix{6} -\markdownBegin -###### -##### -##### -### -###### -\markdownEnd +\def\markdownRendererLineBreak{% + \par + {\it(A forced linebreak)}% + \par +} +\markdownInput{example.md} \bye ``````` +Using a text editor, create a text document named `example.md` with the +following content. Note the two spaces at the end of the first line, which +specify a hard linebreak. Due to the limitations of the \TeX{} input +processor, hard linebreaks would be ignored if we typed them directly into the +`document.tex` document. + +<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> + Next, invoke LuaTeX from the terminal: ``` sh luatex document.tex @@ -14169,7 +13145,11 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> 65536 +> Hello *world*! +> +> *(A forced linebreak)* +> +> _Foo_ bar! ##### \LaTeX{} Example {.unnumbered} @@ -14180,25 +13160,25 @@ following content: \usepackage{markdown} \markdownSetup{ renderers = { - interblockSeparator = {}, - headingOne = 1, - headingTwo = 2, - headingThree = 3, - headingFour = 4, - headingFive = 5, - headingSix = 6, + lineBreak = {% + \par + \emph{(A forced linebreak)}% + \par + }, }, } \begin{document} -\begin{markdown} -###### -##### -##### -### -###### -\end{markdown} +\markdownInput{example.md} \end{document} ``````` +Using a text editor, create a text document named `example.md` with the +following content. Note the two spaces at the end of the first line, which +specify a hard linebreak. Due to the limitations of the \TeX{} input +processor, hard linebreaks would be ignored if we typed them directly into the +`document.tex` document. + +<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> + Next, invoke LuaTeX from the terminal: ``` sh lualatex document.tex @@ -14206,7 +13186,11 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> 65536 +> Hello *world*! +> +> *(A forced linebreak)* +> +> _Foo_ bar! ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -14214,47 +13198,51 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\def\markdownRendererInterblockSeparator{} -\def\markdownRendererHeadingOne{1} -\def\markdownRendererHeadingTwo{2} -\def\markdownRendererHeadingThree{3} -\def\markdownRendererHeadingFour{4} -\def\markdownRendererHeadingFive{5} -\def\markdownRendererHeadingSix{6} +\def\markdownRendererLineBreak{% + \par + \emph{(A forced linebreak)}% + \par +} \starttext -\startmarkdown -###### -##### -##### -### -###### -\stopmarkdown +\markdownInput{example.md} \stoptext ``````` +Using a text editor, create a text document named `example.md` with the +following content. Note the two spaces at the end of the first line, which +specify a hard linebreak. Due to the limitations of the \TeX{} input +processor, hard linebreaks would be ignored if we typed them directly into the +`document.tex` document. + +<pre><code>Hello world! <br/>_Foo_ bar!</code></pre> + Next, invoke LuaTeX from the terminal: ``` sh -context document.tex +luatex document.tex `````` A PDF document named `document.pdf` should be produced and contain the following text: -> 65536 +> Hello *world*! +> +> *(A forced linebreak)* +> +> _Foo_ bar! %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeadingSix{% - \markdownRendererHeadingSixPrototype}% +\def\markdownRendererLineBreak{% + \markdownRendererLineBreakPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headingSix } + { lineBreak } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headingSix } - { 1 } + { lineBreak } + { 0 } \ExplSyntaxOff % \end{macrocode} % \par @@ -14266,9 +13254,11 @@ following text: % % \begin{markdown} -#### Thematic Break Renderer -The \mdef{markdownRendererThematicBreak} macro represents a thematic break. -The macro receives no arguments. +#### Link Renderer +The \mdef{markdownRendererLink} macro represents a hyperlink. It receives +four arguments: the label, the fully escaped \acro{uri} that can be directly +typeset, the raw \acro{uri} that can be used outside typesetting, and the +title of the link. % \end{markdown} % @@ -14280,13 +13270,14 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownRendererThematicBreak{\vfil\break} +\def\markdownRendererLink#1#2#3#4{% + #1 {\tt#2} titled {\it#4}% +} \markdownBegin -This is the first page. - -*** +Please visit [the link][ctan]. -This is the second page. + [ctan]: https://ctan.org/ + (the Comprehensive TeX Archive Network) \markdownEnd \bye ``````` @@ -14297,11 +13288,8 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is the first page. -> -> *** -> -> This is the second page. +> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX +> Archive Network*. ##### \LaTeX{} Example {.unnumbered} @@ -14312,16 +13300,17 @@ following content: \usepackage{markdown} \markdownSetup{ renderers = { - thematicBreak = \newpage, + link = {% + #1 \texttt{#2} titled \emph{#4}% + }, }, } \begin{document} \begin{markdown} -This is the first page. - -*** +Please visit [the link][ctan]. -This is the second page. + [ctan]: https://ctan.org/ + (the Comprehensive TeX Archive Network) \end{markdown} \end{document} ``````` @@ -14332,11 +13321,8 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is the first page. -> -> *** -> -> This is the second page. +> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX +> Archive Network*. ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -14344,14 +13330,15 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\def\markdownRendererThematicBreak{\page[yes]} +\def\markdownRendererLink#1#2#3#4{% + #1 {\tt#2} titled \emph{#4}% +} \starttext \startmarkdown -This is the first page. - -*** +Please visit [the link][ctan]. -This is the second page. + [ctan]: https://ctan.org/ + (the Comprehensive TeX Archive Network) \stopmarkdown \stoptext ``````` @@ -14362,66 +13349,261 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> This is the first page. -> -> *** -> -> This is the second page. +> Please visit the link <https://ctan.org/> titled *the Comprehensive TeX +> Archive Network*. %</manual-tokens> %<*tex> % \fi -% \begin{markdown} % -% The \mdef{markdownRendererHorizontalRule} and -% \mdef{markdownRendererHorizontalRulePrototype} macros have been deprecated -% and will be removed in Markdown 3.0.0. +% \begin{macrocode} +\def\markdownRendererLink{% + \markdownRendererLinkPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { link } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { link } + { 4 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi % +% \begin{markdown} + +#### Markdown Document Renderers +The \mdef{markdownRendererDocumentBegin} and \mdef{markdownRendererDocumentEnd} +macros represent the beginning and the end of a *markdown* document. The macros +receive no arguments. + +A \TeX{} document may contain any number of markdown documents. Additionally, +markdown documents may appear not only in a sequence, but several markdown +documents may also be *nested*. Redefinitions of the macros should take this +into account. + % \end{markdown} +% +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `nested.md` with the +following content: +``` md +This is a *nested* markdown document. +``` + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[contentBlocks]{markdown} +\markdownSetup{ + renderers = { + contentBlock = {% + \markdownInput{#3}% + }, + documentBegin = {% + \par + \emph{(The beginning of a document)} + \par + \begingroup + \markdownSetup{snippet=first-nesting-level}% + }, + documentEnd = {% + \endgroup + \par + \emph{(The end of a document)} + \par + }, + }, +} +\markdownSetupSnippet{first-nesting-level}{ + renderers = { + documentBegin = { + \par + \emph{(The beginning of a nested document)} + \par + \begingroup + \markdownSetup{snippet=second-nesting-level-and-below} + }, + }, +} +\markdownSetupSnippet{second-nesting-level-and-below}{ + renderers = { + documentBegin = { + \par + \emph{(The beginning of a nested document)} + \par + \begingroup + }, + documentEnd = { + \endgroup + \par + \emph{(The end of a nested document)} + \par + }, + }, +} +\begin{document} +\begin{markdown} +Hello *world*! + +/nested.md + +_Foo_ bar! +\end{markdown} +\begin{markdown} + +Bar baz! + +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> *(The beginning of a document)* +> +> Hello *world*! +> +> *(The beginning of a nested document)* +> +> This is a *nested* markdown document. +> +> *(The end of a nested document)* +> +> _Foo_ bar! +> +> *(The end of a document)* +> +> *(The beginning of a document)* +> +> Bar baz! +> +> *(The end of a document)* + +%</manual-tokens> +%<*tex> +% \fi +% % \begin{macrocode} +\def\markdownRendererDocumentBegin{% + \markdownRendererDocumentBeginPrototype}% \ExplSyntaxOn -\cs_new:Npn - \markdownRendererThematicBreak - { - \cs_if_exist:NTF - \markdownRendererHorizontalRule - { - \markdownWarning - { - Horizontal~rule~renderer~has~been~deprecated,~ - to~be~removed~in~Markdown~3.0.0 - } - \markdownRendererHorizontalRule - } - { - \cs_if_exist:NTF - \markdownRendererHorizontalRulePrototype - { - \markdownWarning - { - Horizontal~rule~renderer~prototype~has~been~deprecated,~ - to~be~removed~in~Markdown~3.0.0 - } - \markdownRendererHorizontalRulePrototype - } - { - \markdownRendererThematicBreakPrototype - } - } - } \seq_gput_right:Nn \g_@@_renderers_seq - { horizontalRule } + { documentBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { horizontalRule } + { documentBegin } { 0 } +\ExplSyntaxOff +\def\markdownRendererDocumentEnd{% + \markdownRendererDocumentEndPrototype}% +\ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { thematicBreak } + { documentEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { thematicBreak } + { documentEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Non-Breaking Space Renderer +The \mdef{markdownRendererNbsp} macro represents a non-breaking space. + +% \end{markdown} +% +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.bib` with the +following content: +``` bib +@book{knuth:tex, + author = "Knuth, Donald Ervin", + title = "The \TeX book, volume A of Computers and typesetting", + publisher = "Addison-Wesley", + year = "1984" +} +``````` +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[ + citations, + citationNbsps, +]{markdown} +\markdownSetup{ + renderers = { + nbsp = {$\cdot$}, + }, +} +\begin{document} + +\begin{markdown} +The TeXbook [@knuth:tex, p. 123 and 130] is good. +\end{markdown} + +\bibliographystyle{plain} +\bibliography{document.bib} + +\end{document} +``````` +Next, invoke LuaTeX and BibTeX from the terminal: +``` sh +lualatex document.tex +bibtex document.aux +lualatex document.tex +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> The TeXbook [1, p.·123·and·130] is good. +> +> ### References +> [1] Donald Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._ +> Addison-Wesley, 1984. + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererNbsp{% + \markdownRendererNbspPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { nbsp } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { nbsp } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -14596,92 +13778,102 @@ following text: % % \begin{markdown} -#### Parenthesized Citations Renderer -The \mdef{markdownRendererCite} macro represents a string of one or more -parenthetical citations. This macro will only be produced, when the -\Opt{citations} option is enabled. The macro receives the parameter -`{`\meta{number of citations}`}` followed by \meta{suppress author} -`{`\meta{prenote}`}{`\meta{postnote}`}{`\meta{name}`}` repeated -\meta{number of citations} times. The \meta{suppress author} parameter is -either the token `-`, when the author's name is to be suppressed, or `+` -otherwise. +#### Ordered List Renderers +The \mdef{markdownRendererOlBegin} macro represents the beginning of an +ordered list that contains an item with several paragraphs of text (the +list is not tight). This macro will only be produced, when the \Opt{fancyLists} +option is disabled. The macro receives no arguments. % \end{markdown} % % \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererOlBegin{% + \markdownRendererOlBeginPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { olBegin } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { olBegin } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -##### \LaTeX{} Example {.unnumbered} +The \mdef{markdownRendererOlBeginTight} macro represents the beginning of an +ordered list that contains no item with several paragraphs of text (the +list is tight). This macro will only be produced, when the \Opt{tightLists} +option is enabled and the \Opt{fancyLists} option is disabled. The macro +receives no arguments. -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[citations]{markdown} -\newcount\citationsCounter -\newcount\citationsTotal -\makeatletter -\def\citations#1#2#3#4{% - a parenthesized citation \emph{#4} - \advance\citationsCounter by 1\relax - \ifx\relax#2\relax - \ifx\relax#3\relax\else - with a postfix \emph{#3}% - \fi - \else - with a prefix \emph{#2}% - \ifx\relax#3\relax\else - \ and a postfix \emph{#3}% - \fi - \fi - \ifnum\citationsCounter>\citationsTotal\relax - .% - \expandafter\@gobble - \else - , and - \fi\citations} -\makeatother -\markdownSetup{ - renderers = { - cite = {% - \citationsCounter=1% - \citationsTotal=#1% - This is - \expandafter\citations - }, - }, -} -\begin{document} -\begin{markdown} -[see @abrahams90, pp. 12; @eijkhout91, pp. 34] -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererOlBeginTight{% + \markdownRendererOlBeginTightPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { olBeginTight } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { olBeginTight } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -> This is a parenthesized citation *abrahams90* with a prefix see -> and a postfix *pp. 12*, and a citation *eijkhout91* with a -> postfix *pp. 34*. +The \mdef{markdownRendererFancyOlBegin} macro represents the beginning of a +fancy ordered list that contains an item with several paragraphs of text (the +list is not tight). This macro will only be produced, when the \Opt{fancyLists} +option is enabled. The macro receives two arguments: the style of the list item +labels (`Decimal`, `LowerRoman`, `UpperRoman`, `LowerAlpha`, and `UpperAlpha`), +and the style of delimiters between list item labels and texts (`Default`, +`OneParen`, and `Period`). +% \end{markdown} +% +% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererCite{% - \markdownRendererCitePrototype}% +\def\markdownRendererFancyOlBegin{% + \markdownRendererFancyOlBeginPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { cite } + { fancyOlBegin } \prop_gput:Nnn \g_@@_renderer_arities_prop - { cite } - { 1 } + { fancyOlBegin } + { 2 } \ExplSyntaxOff % \end{macrocode} % \par @@ -14693,86 +13885,132 @@ following text: % % \begin{markdown} -#### Text Citations Renderer -The \mdef{markdownRendererTextCite} macro represents a string of one or more -text citations. This macro will only be produced, when the -\Opt{citations} option is enabled. The macro receives parameters in the same -format as the \mref{markdownRendererCite} macro. +The \mdef{markdownRendererFancyOlBeginTight} macro represents the beginning of +a fancy ordered list that contains no item with several paragraphs of text (the +list is tight). This macro will only be produced, when the \Opt{fancyLists} +and \Opt{tightLists} options are enabled. The macro receives two arguments: the +style of the list item labels, and the style of delimiters between list +item labels and texts. See the \mref{markdownRendererFancyOlBegin} macro for +the valid style values. % \end{markdown} % % \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererFancyOlBeginTight{% + \markdownRendererFancyOlBeginTightPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { fancyOlBeginTight } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { fancyOlBeginTight } + { 2 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -##### \LaTeX{} Example {.unnumbered} +The \mdef{markdownRendererOlItem} macro represents an item in an ordered list. +This macro will only be produced, when the \Opt{startNumber} option is +disabled and the \Opt{fancyLists} option is disabled. The macro receives no +arguments. -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[citations]{markdown} -\newcount\citationsCounter -\newcount\citationsTotal -\makeatletter -\def\citations#1#2#3#4{% - a text citation \emph{#4} - \advance\citationsCounter by 1\relax - \ifx\relax#2\relax - \ifx\relax#3\relax\else - with a postfix \emph{#3}% - \fi - \else - with a prefix \emph{#2}% - \ifx\relax#3\relax\else - \ and a postfix \emph{#3}% - \fi - \fi - \ifnum\citationsCounter>\citationsTotal\relax - .% - \expandafter\@gobble - \else - , and - \fi\citations} -\makeatother -\markdownSetup{ - renderers = { - textCite = {% - \citationsCounter=1% - \citationsTotal=#1% - This is - \expandafter\citations - }, - }, -} -\begin{document} -\begin{markdown} -@abrahams90 [pp. 12; also @eijkhout91] -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererOlItem{% + \markdownRendererOlItemPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { olItem } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { olItem } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -> This is a text citation *abrahams90* with a postfix *pp. 12*, -> and a citation *eijkhout91* with a prefix *also*. +The \mdef{markdownRendererOlItemEnd} macro represents the end of an item in +an ordered list. This macro will only be produced, when the \Opt{fancyLists} +option is disabled. The macro receives no arguments. +% \end{markdown} +% +% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererTextCite{% - \markdownRendererTextCitePrototype}% +\def\markdownRendererOlItemEnd{% + \markdownRendererOlItemEndPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { textCite } + { olItemEnd } \prop_gput:Nnn \g_@@_renderer_arities_prop - { textCite } + { olItemEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererOlItemWithNumber} macro represents an item in an +ordered list. This macro will only be produced, when the \Opt{startNumber} +option is enabled and the \Opt{fancyLists} option is disabled. The macro +receives a single numeric argument that corresponds to the item number. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererOlItemWithNumber{% + \markdownRendererOlItemWithNumberPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { olItemWithNumber } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { olItemWithNumber } { 1 } \ExplSyntaxOff % \end{macrocode} @@ -14785,122 +14023,165 @@ following text: % % \begin{markdown} -#### Table Renderer -The \mdef{markdownRendererTable} macro represents a table. This macro will only -be produced, when the \Opt{pipeTables} option is enabled. The macro receives the -parameters `{`\meta{caption}`}{`\meta{number of rows}`}{`\meta{number of columns}`}` -followed by `{`\meta{alignments}`}` and then by `{`\meta{row}`}` repeated -\meta{number of rows} times, where \meta{row} is `{`\meta{column}`}` repeated -\meta{number of columns} times, \meta{alignments} is \meta{alignment} repeated -\meta{number of columns} times, and \meta{alignment} is one of the following: +The \mdef{markdownRendererFancyOlItem} macro represents an item in a fancy +ordered list. This macro will only be produced, when the \Opt{startNumber} +option is disabled and the \Opt{fancyLists} option is enabled. The macro receives +no arguments. -- `d` -- The corresponding column has an unspecified (default) alignment. -- `l` -- The corresponding column is left-aligned. -- `c` -- The corresponding column is centered. -- `r` -- The corresponding column is right-aligned. +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererFancyOlItem{% + \markdownRendererFancyOlItemPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { fancyOlItem } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { fancyOlItem } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererFancyOlItemEnd} macro represents the end of an item in +a fancy ordered list. This macro will only be produced, when the \Opt{fancyLists} +option is enabled. The macro receives no arguments. % \end{markdown} % % \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererFancyOlItemEnd{% + \markdownRendererFancyOlItemEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { fancyOlItemEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { fancyOlItemEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -##### \LaTeX{} Example {.unnumbered} +The \mdef{markdownRendererFancyOlItemWithNumber} macro represents an item in a +fancy ordered list. This macro will only be produced, when the \Opt{startNumber} +and \Opt{fancyLists} options are enabled. The macro receives a single numeric +argument that corresponds to the item number. -Using a text editor, create a text document named `document.tex` with the -following content: -``` tex -\documentclass{article} -\usepackage[pipeTables, tableCaptions]{markdown} -\newcount\rowCounter -\newcount\columnCounter -\makeatletter -\def\processRow#1{% - \columnCounter=1% - \ifnum\rowCounter=0\relax - As for the alignment, - \else - In row \the\rowCounter, - \fi - \processColumn#1 - \advance\rowCounter by 1\relax - \ifnum\rowCounter>\rowTotal\relax - \expandafter\@gobble - \fi\processRow}% -\def\processColumn#1{% - column number \the\columnCounter{} - \ifnum\rowCounter=0\relax - \if#1d{}has default alignment\fi - \if#1l{}is left-aligned\fi - \if#1c{}is centered\fi - \if#1r{}is right-aligned\fi - \else - says \emph{#1}% - \fi - \advance\columnCounter by 1\relax - \ifnum\columnCounter<\columnTotal\relax, \fi - \ifnum\columnCounter=\columnTotal\relax, and \fi - \ifnum\columnCounter>\columnTotal\relax - .\expandafter\@gobble - \fi\processColumn}% -\makeatother -\markdownSetup{ - renderers = { - table = {% - This is a table with caption \emph{#1} that is #3 colums wide - and #2 rows long. - \rowCounter=0% - \def\rowTotal{#2}% - \def\columnTotal{#3}% - \processRow - }, - }, -} -\begin{document} -\begin{markdown} -| Right | Left | Default | Center | -|------:|:-----|---------|:------:| -| 12 | 12 | 12 | 12 | -| 123 | 123 | 123 | 123 | -| 1 | 1 | 1 | 1 | +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererFancyOlItemWithNumber{% + \markdownRendererFancyOlItemWithNumberPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { fancyOlItemWithNumber } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { fancyOlItemWithNumber } + { 1 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} - : Demonstration of pipe table syntax -\end{markdown} -\end{document} -``````` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: +The \mdef{markdownRendererOlEnd} macro represents the end of an ordered list +that contains an item with several paragraphs of text (the list is not +tight). This macro will only be produced, when the \Opt{fancyLists} option is +disabled. The macro receives no arguments. -> This is a table with caption *Demonstration of pipe table syntax* that is 4 -> colums wide and 4 rows long. As for the alignment, column number 1 is -> right-aligned, column number 2 is left-aligned, column number 3 has default -> alignment, and column number 4 is centered. In row 1, column number 1 says -> *Right*, column number 2 says *Left*, column number 3 says *Default*, and -> column number 4 says *Center*. In row 2, column number 1 says *12*, column -> number 2 says *12*, column number 3 says *12*, and column number 4 says *12*. -> In row 3, column number 1 says *123*, column number 2 says *123*, column -> number 3 says *123*, and column number 4 says *123*. In row 4, column number -> 1 says *1*, column number 2 says *1*, column number 3 says *1*, and column -> number 4 says *1*. +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererOlEnd{% + \markdownRendererOlEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { olEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { olEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} +The \mdef{markdownRendererOlEndTight} macro represents the end of an ordered +list that contains no item with several paragraphs of text (the list is +tight). This macro will only be produced, when the \Opt{tightLists} option is +enabled and the \Opt{fancyLists} option is disabled. The macro receives no +arguments. +% \end{markdown} +% +% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererTable{% - \markdownRendererTablePrototype}% +\def\markdownRendererOlEndTight{% + \markdownRendererOlEndTightPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { table } + { olEndTight } \prop_gput:Nnn \g_@@_renderer_arities_prop - { table } - { 3 } + { olEndTight } + { 0 } \ExplSyntaxOff % \end{macrocode} % \par @@ -14912,110 +14193,319 @@ following text: % % \begin{markdown} -#### HTML Comment Renderers +The \mdef{markdownRendererFancyOlEnd} macro represents the end of a fancy +ordered list that contains an item with several paragraphs of text (the list +is not tight). This macro will only be produced, when the \Opt{fancyLists} +option is enabled. The macro receives no arguments. -The \mdef{markdownRendererInlineHtmlComment} macro represents the contents of an -inline \acro{HTML} comment. This macro will only be produced, when the -\Opt{html} option is enabled. The macro receives a single argument that -corresponds to the contents of the \acro{HTML} comment. +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererFancyOlEnd{% + \markdownRendererFancyOlEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { fancyOlEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { fancyOlEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -The \mdef{markdownRendererBlockHtmlCommentBegin} and -\mdef{markdownRendererBlockHtmlCommentEnd} macros represent the beginning -and the end of a block \acro{HTML} comment. The macros receive no arguments. +The \mdef{markdownRendererFancyOlEndTight} macro represents the end of a +fancy ordered list that contains no item with several paragraphs of text (the +list is tight). This macro will only be produced, when the \Opt{fancyLists} +and \Opt{tightLists} options are enabled. The macro receives no arguments. % \end{markdown} % % \iffalse +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionTightLists{true} +\def\markdownOptionStartNumber{true} + +\def\markdownRendererInterblockSeparator{} +\def\markdownRendererOlBeginTight{ (} +\def\markdownRendererOlItemWithNumber#1{% + \ifnum #1=1\relax + the first + \else + \ifnum #1=2\relax + , the second + \else + , and the third + \fi + \fi +} +\def\markdownRendererOlItemEnd{} +\def\markdownRendererOlEndTight{).} + +\markdownBegin +This is a tight list + +1. item +2. item +3. item +\markdownEnd + +\def\markdownRendererInterblockSeparator{% + :\par + \def\markdownRendererInterblockSeparator{\par}% +} +\def\markdownRendererOlBegin{} +\def\markdownRendererOlItemWithNumber#1{% + #1.\kern 0.5em% + This is the + \ifnum #1=1\relax + first + \else + \ifnum #1=2\relax + second + \else + third + \fi + \fi +} +\def\markdownRendererOlItemEnd{.\par} +\def\markdownRendererOlEnd{} + +\markdownBegin +This is a loose list + +1. item + +2. item + +3. item +\markdownEnd + +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> This is a tight list (the first item, the second item, and the third item). +> +> This is a loose list: +> +> 1. This is the first item. +> +> 2. This is the second item. +> +> 3. This is the third item. + ##### \LaTeX{} Example {.unnumbered} Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[html]{markdown} -\usepackage{marginnote} -\markdownSetup{ +\usepackage[tightLists, startNumber]{markdown} +\begin{document} + +\begin{markdown*}{ renderers = { - inlineHtmlComment = {\marginnote{#1}}, - blockHtmlCommentBegin = {\begin{quote}}, - blockHtmlCommentEnd = {\end{quote}}, - }, + interblockSeparator = {}, + olBeginTight = { (}, + olItemWithNumber = {% + \ifnum #1=1\relax + the first + \else + \ifnum #1=2\relax + , the second + \else + , and the third + \fi + \fi + }, + olItemEnd = {}, + olEndTight = {).}, + }, } -\begin{document} -\begin{markdown} -A useful use of inline HTML comments are side notes. -<!-- Side notes are displayed in the horizontal margins next to the relevant -passages, which makes them *easier for the reader to find* than notes. --> +This is a tight list -We can render block HTML comments as blockquotes: +1. item +2. item +3. item +\end{markdown*} -<!-- -Here is a block HTML comment with a code example that a programmer might understand: +\begin{markdown*}{ + renderers = { + interblockSeparator = {% + :\par + \def\markdownRendererInterblockSeparator{\par}% + }, + olBeginTight = {\begin{enumerate}}, + olItemWithNumber = {% + \item This is the + \ifnum #1=1\relax + first + \else + \ifnum #1=2\relax + second + \else + third + \fi + \fi + }, + olItemEnd = {.}, + olEnd = {\end{enumerate}}, + }, +} +This is a loose list + +1. item + +2. item + +3. item +\end{markdown*} - foo = bar + baz - 42 ---> -\end{markdown} \end{document} ``````` Next, invoke LuaTeX from the terminal: ``` sh lualatex document.tex -lualatex document.tex `````` A PDF document named `document.pdf` should be produced and contain the -following body text: +following text: -> A useful use of HTML comments are side notes. +> This is a tight list (the first item, the second item, and the third item). > -> We can render block HTML comments as blockquotes: +> This is a loose list: > -> > Here is a block HTML comment with a code example that a programmer might -> > understand: -> > -> > foo = bar + baz - 42 +> 1. This is the first item. +> +> 2. This is the second item. +> +> 3. This is the third item. -The horizontal margins should contain the following text: +##### \Hologo{ConTeXt} Example {.unnumbered} -> Side notes are displayed in the horizontal margins next to the relevant -> passages, which makes them *easier for the reader to find* than notes. +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\setupmarkdown + [ + tightLists = yes, + startNumber = yes, + ] +\starttext + +\def\markdownRendererInterblockSeparator{} +\def\markdownRendererOlBeginTight{ (} +\def\markdownRendererOlItemWithNumber#1{% + \ifnum #1=1\relax + the first + \else + \ifnum #1=2\relax + , the second + \else + , and the third + \fi + \fi +} +\def\markdownRendererOlItemEnd{} +\def\markdownRendererOlEndTight{).} + +\startmarkdown +This is a tight list + +1. item +2. item +3. item +\stopmarkdown + +\def\markdownRendererInterblockSeparator{% + :\par + \def\markdownRendererInterblockSeparator{\par}% +} +\def\markdownRendererOlBegin{\startitemize} +\def\markdownRendererOlItemWithNumber#1{% + \sym{#1.} + This is the + \ifnum #1=1\relax + first + \else + \ifnum #1=2\relax + second + \else + third + \fi + \fi +} +\def\markdownRendererOlItemEnd{.\par} +\def\markdownRendererOlEnd{\stopitemize} + +\startmarkdown +This is a loose list + +1. item + +2. item + +3. item +\stopmarkdown + +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> This is a tight list (the first item, the second item, and the third item). +> +> This is a loose list: +> +> 1. This is the first item. +> +> 2. This is the second item. +> +> 3. This is the third item. %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererInlineHtmlComment{% - \markdownRendererInlineHtmlCommentPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { inlineHtmlComment } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { inlineHtmlComment } - { 1 } -\ExplSyntaxOff -\def\markdownRendererBlockHtmlCommentBegin{% - \markdownRendererBlockHtmlCommentBeginPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { blockHtmlCommentBegin } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { blockHtmlCommentBegin } - { 0 } -\ExplSyntaxOff -\def\markdownRendererBlockHtmlCommentEnd{% - \markdownRendererBlockHtmlCommentEndPrototype}% +\def\markdownRendererFancyOlEndTight{% + \markdownRendererFancyOlEndTightPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { blockHtmlCommentEnd } + { fancyOlEndTight } \prop_gput:Nnn \g_@@_renderer_arities_prop - { blockHtmlCommentEnd } + { fancyOlEndTight } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -15028,17 +14518,15 @@ The horizontal margins should contain the following text: % % \begin{markdown} -#### HTML Tag and Element Renderers - -The \mdef{markdownRendererInlineHtmlTag} macro represents an opening, closing, -or empty inline \acro{HTML} tag. This macro will only be produced, when the -\Opt{html} option is enabled. The macro receives a single argument that -corresponds to the contents of the \acro{HTML} tag. - -The \mdef{markdownRendererInputBlockHtmlElement} macro represents a block -\acro{HTML} element. This macro will only be produced, when the \Opt{html} -option is enabled. The macro receives a single argument that filename of a file -containing the contents of the \acro{HTML} element. +#### Parenthesized Citations Renderer +The \mdef{markdownRendererCite} macro represents a string of one or more +parenthetical citations. This macro will only be produced, when the +\Opt{citations} option is enabled. The macro receives the parameter +`{`\meta{number of citations}`}` followed by \meta{suppress author} +`{`\meta{prenote}`}{`\meta{postnote}`}{`\meta{name}`}` repeated +\meta{number of citations} times. The \meta{suppress author} parameter is +either the token `-`, when the author's name is to be suppressed, or `+` +otherwise. % \end{markdown} % @@ -15050,61 +14538,108 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[html]{markdown} -\usepackage{marginnote} -\usepackage{verbatim} +\usepackage[citations]{markdown} +\newcount\citationsCounter +\newcount\citationsTotal +\makeatletter +\def\citations#1#2#3#4{% + a parenthesized citation \emph{#4} + \advance\citationsCounter by 1\relax + \ifx\relax#2\relax + \ifx\relax#3\relax\else + with a postfix \emph{#3}% + \fi + \else + with a prefix \emph{#2}% + \ifx\relax#3\relax\else + \ and a postfix \emph{#3}% + \fi + \fi + \ifnum\citationsCounter>\citationsTotal\relax + .% + \expandafter\@gobble + \else + , and + \fi\citations} +\makeatother \markdownSetup{ renderers = { - inlineHtmlTag = {\textbf{#1}}, - inputBlockHtmlElement = {\verbatiminput{#1}}, + cite = {% + \citationsCounter=1% + \citationsTotal=#1% + This is + \expandafter\citations + }, }, } \begin{document} \begin{markdown} -<b>_Hello,_ world!</b><br/> - -<div>_Hello,_ world!</div> +[see @abrahams90, pp. 12; @eijkhout91, pp. 34] \end{markdown} \end{document} ``````` Next, invoke LuaTeX from the terminal: ``` sh lualatex document.tex -lualatex document.tex `````` A PDF document named `document.pdf` should be produced and contain the -following body text: +following text: -> **<b>**_Hello,_ world!**</b><br/>** -> -> <div>_Hello,_ world!</div> +> This is a parenthesized citation *abrahams90* with a prefix see +> and a postfix *pp. 12*, and a citation *eijkhout91* with a +> postfix *pp. 34*. %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererInlineHtmlTag{% - \markdownRendererInlineHtmlTagPrototype}% +\def\markdownRendererCite{% + \markdownRendererCitePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inlineHtmlTag } + { cite } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inlineHtmlTag } + { cite } { 1 } \ExplSyntaxOff -\def\markdownRendererInputBlockHtmlElement{% - \markdownRendererInputBlockHtmlElementPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Raw Content Renderers +The \mdef{markdownRendererInputRawInline} macro represents an inline raw span. +The macro receives two arguments: the filename of a file contaning the inline +raw span contents and the raw attribute that designates the format of the +inline raw span. This macro will only be produced, when the \Opt{rawAttribute} +option is enabled. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererInputRawInline{% + \markdownRendererInputRawInlinePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inputBlockHtmlElement } + { inputRawInline } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inputBlockHtmlElement } - { 1 } + { inputRawInline } + { 2 } \ExplSyntaxOff % \end{macrocode} % \par @@ -15116,25 +14651,11 @@ following body text: % % \begin{markdown} -#### Attribute Renderers -The following macros are only produced, when the \Opt{headerAttributes} option -is enabled. - -\mdef{markdownRendererAttributeIdentifier} represents the \meta{identifier} of -a markdown element (`id="`\meta{identifier}`"` in HTML and `#`\meta{identifier} -in Markdown's \Opt{headerAttributes} syntax extension). The macro receives a -single attribute that corresponds to the \meta{identifier}. - -\mdef{markdownRendererAttributeClassName} represents the \meta{class name} of a -markdown element (`class="`\meta{class name} ...`"` in HTML and -`.`\meta{class name} in Markdown's \Opt{headerAttributes} syntax extension). -The macro receives a single attribute that corresponds to the \meta{class -name}. - -\mdef{markdownRendererAttributeKeyValue} represents a HTML attribute in the form -\meta{key}`=`\meta{value} that is neither an identifier nor a class name. -The macro receives two attributes that correspond to the \meta{key} and the -\meta{value}, respectively. +The \mdef{markdownRendererInputRawBlock} macro represents a raw block. The +macro receives two arguments: the filename of a file contaning the raw block +and the raw attribute that designates the format of the raw block. This macro +will only be produced, when the \Opt{rawAttribute} and \Opt{fencedCode} options +are enabled. % \end{markdown} % @@ -15144,40 +14665,39 @@ The macro receives two attributes that correspond to the \meta{key} and the Using a text editor, create a text document named `document.tex` with the following content: -``` tex +```` tex \documentclass{article} -\usepackage[headerAttributes, underscores=false]{markdown} +\usepackage[rawAttribute, fencedCode]{markdown} +\usepackage{expl3} +\ExplSyntaxOn +\cs_new:Nn + \display_raw_content:nn + { + % If the raw attribute is TeX, execute the content as a TeX document. + \str_if_eq:nnTF + { #2 } + { tex } + { \markdownEscape { #1 } } + % Otherwise, ignore the content. + { } + } \markdownSetup{ renderers = { - attributeIdentifier = {% - \par - \emph{(Identifier: #1)} - \par - }, - attributeClassName = {% - \par - \emph{(Class name: #1)} - \par - }, - attributeKeyValue = {% - \par - \emph{(Key: #1, Value: #2)} - \par - }, + rawInline = { \display_raw_content:nn { #1 } { #2 } }, + rawBlock = { \display_raw_content:nn { #1 } { #2 } } }, } +\ExplSyntaxOff \begin{document} \begin{markdown} +`$H_2 O$`{=tex} is a liquid. -# First top-level heading {jane=doe} - -## A subheading {#identifier} - -# Second top-level heading {.class_name} - +``` {=html} +<p>Here is some HTML content that will be ignored.</p> +``` \end{markdown} \end{document} -``````` +```` Next, invoke LuaTeX from the terminal: ``` sh lualatex document.tex @@ -15185,54 +14705,22 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> # First top-level heading -> -> *(Key: Jane, Value: Doe)* -> -> ## A subheading -> -> *(Identifier: identifier)* -> -> # Second top-level heading -> -> *(Class name: class\_name)* +> H~2~O is a liquid. %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererAttributeIdentifier{% - \markdownRendererAttributeIdentifierPrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { attributeIdentifier } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { attributeIdentifier } - { 1 } -\ExplSyntaxOff -\def\markdownRendererAttributeClassName{% - \markdownRendererAttributeClassNamePrototype}% -\ExplSyntaxOn -\seq_gput_right:Nn - \g_@@_renderers_seq - { attributeClassName } -\prop_gput:Nnn - \g_@@_renderer_arities_prop - { attributeClassName } - { 1 } -\ExplSyntaxOff -\def\markdownRendererAttributeKeyValue{% - \markdownRendererAttributeKeyValuePrototype}% +\def\markdownRendererInputRawBlock{% + \markdownRendererInputRawBlockPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { attributeKeyValue } + { inputRawBlock } \prop_gput:Nnn \g_@@_renderer_arities_prop - { attributeKeyValue } + { inputRawBlock } { 2 } \ExplSyntaxOff % \end{macrocode} @@ -15245,49 +14733,70 @@ following text: % % \begin{markdown} -#### Header Attribute Context Renderers -The following macros are only produced, when the \Opt{headerAttributes} option -is enabled. +#### Special Character Renderers +The following macros replace any special plain \TeX{} characters, including +% \iffalse +the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text: -The \mdef{markdownRendererHeaderAttributeContextBegin} and -\mdef{markdownRendererHeaderAttributeContextEnd} macros represent the beginning -and the end of a section in which the attributes of a heading apply. The macros -receive no arguments. +- \mdef{markdownRendererAmpersand} replaces the ampersand (`&`). +- \mdef{markdownRendererBackslash} replaces the backslash (`\`). +- \mdef{markdownRendererCircumflex} replaces the circumflex (`^`). +- \mdef{markdownRendererDollarSign} replaces the dollar sign (`$`). +- \mdef{markdownRendererHash} replaces the hash sign (`#`). +- \mdef{markdownRendererLeftBrace} replaces the left brace (`{`). +- \mdef{markdownRendererPercentSign} replaces the percent sign (`%`). +- \mdef{markdownRendererPipe} replaces the pipe character (`|`). +- \mdef{markdownRendererRightBrace} replaces the right brace (`}`). +- \mdef{markdownRendererTilde} replaces the tilde (`~`). +- \mdef{markdownRendererUnderscore} replaces the underscore (`_`). + +% \fi +% the active pipe character (`|`) of \Hologo{ConTeXt}, in the input text. +% These macros will only be produced, when the \Opt{hybrid} option is +% `false`. % \end{markdown} % % \iffalse +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content. We will make the tilde behave as if it were written in +\TeX{}, where it represents a non-breaking space. +``` tex +\input markdown +\def\markdownRendererTilde{~} +\markdownBegin +Bartel~Leendert van~der~Waerden +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text, where the middot (`·`) denotes a non-breaking space: + +> Bartel·Leendert van·der·Waerden + ##### \LaTeX{} Example {.unnumbered} Using a text editor, create a text document named `document.tex` with the -following content: +following content. We will make the tilde behave as if it were written in +\TeX{}, where it represents a non-breaking space. ``` tex \documentclass{article} -\usepackage[headerAttributes]{markdown} +\usepackage{markdown} \markdownSetup{ renderers = { - headerAttributeContextBegin = {% - \par - \emph{(The beginning of a header attribute context)} - \par - }, - headerAttributeContextBegin = {% - \par - \emph{(The end of a header attribute context)} - \par - }, + tilde = ~, }, } \begin{document} \begin{markdown} - -# First top-level heading - -## A subheading {#identifier} - -# Second top-level heading {.class_name} - +Bartel~Leendert van~der~Waerden \end{markdown} \end{document} ``````` @@ -15296,47 +14805,157 @@ Next, invoke LuaTeX from the terminal: lualatex document.tex `````` A PDF document named `document.pdf` should be produced and contain the -following text: +following text, where the middot (`·`) denotes a non-breaking space: -> # First top-level heading -> -> *(The beginning of a header attribute context)* -> -> ## A subheading -> -> *(The end of a header attribute context)* -> -> *(The beginning of a header attribute context)* -> -> # Second top-level heading -> -> *(The end of a header attribute context)* +> Bartel·Leendert van·der·Waerden + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content. We will make the tilde behave as if it were written in +\TeX{}, where it represents a non-breaking space. +``` tex +\usemodule[t][markdown] +\def\markdownRendererTilde{~} +\starttext +\startmarkdown +Bartel~Leendert van~der~Waerden +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text, where the middot (`·`) denotes a non-breaking space: + +> Bartel·Leendert van·der·Waerden %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererHeaderAttributeContextBegin{% - \markdownRendererHeaderAttributeContextBeginPrototype}% +\def\markdownRendererLeftBrace{% + \markdownRendererLeftBracePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headerAttributeContextBegin } + { leftBrace } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headerAttributeContextBegin } + { leftBrace } { 0 } \ExplSyntaxOff -\def\markdownRendererHeaderAttributeContextEnd{% - \markdownRendererHeaderAttributeContextEndPrototype}% +\def\markdownRendererRightBrace{% + \markdownRendererRightBracePrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { headerAttributeContextEnd } + { rightBrace } \prop_gput:Nnn \g_@@_renderer_arities_prop - { headerAttributeContextEnd } + { rightBrace } + { 0 } +\ExplSyntaxOff +\def\markdownRendererDollarSign{% + \markdownRendererDollarSignPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { dollarSign } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { dollarSign } + { 0 } +\ExplSyntaxOff +\def\markdownRendererPercentSign{% + \markdownRendererPercentSignPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { percentSign } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { percentSign } + { 0 } +\ExplSyntaxOff +\def\markdownRendererAmpersand{% + \markdownRendererAmpersandPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { ampersand } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { ampersand } + { 0 } +\ExplSyntaxOff +\def\markdownRendererUnderscore{% + \markdownRendererUnderscorePrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { underscore } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { underscore } + { 0 } +\ExplSyntaxOff +\def\markdownRendererHash{% + \markdownRendererHashPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { hash } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { hash } + { 0 } +\ExplSyntaxOff +\def\markdownRendererCircumflex{% + \markdownRendererCircumflexPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { circumflex } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { circumflex } + { 0 } +\ExplSyntaxOff +\def\markdownRendererBackslash{% + \markdownRendererBackslashPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { backslash } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { backslash } + { 0 } +\ExplSyntaxOff +\def\markdownRendererTilde{% + \markdownRendererTildePrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { tilde } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { tilde } + { 0 } +\ExplSyntaxOff +\def\markdownRendererPipe{% + \markdownRendererPipePrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { pipe } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { pipe } { 0 } \ExplSyntaxOff % \end{macrocode} @@ -15459,6 +15078,113 @@ following text: % % \begin{markdown} +#### Subscript Renderer +The \mdef{markdownRendererSubscript} macro represents a subscript span of +text. The macro receives a single argument that corresponds to the subscript +span of text. This macro will only be produced, when the \Opt{subscripts} +option is enabled. + +% \end{markdown} +% +% \iffalse + +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionSubscripts{true} +\def\markdownRendererSubscript#1{ (#1 moles) and } +\markdownBegin +H~2~O is a liquid. +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> H (2 moles) and O is a liquid. + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[subscripts]{markdown} +\markdownSetup{ + renderers = { + subscript = { (#1 moles) and }, + }, +} +\begin{document} +\begin{markdown} +H~2~O is a liquid. +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> H (2 moles) and O is a liquid. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\setupmarkdown[subscripts = yes] +\def\markdownRendererSubscript#1{ (#1 moles) and } +\starttext +\startmarkdown +H~2~O is a liquid. +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> H (2 moles) and O is a liquid. + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererSubscript{% + \markdownRendererSubscriptPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { subscript } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { subscript } + { 1 } +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + #### Superscript Renderer The \mdef{markdownRendererSuperscript} macro represents a superscript span of text. The macro receives a single argument that corresponds to the superscript @@ -15567,11 +15293,228 @@ following text: % % \begin{markdown} -#### Subscript Renderer -The \mdef{markdownRendererSubscript} macro represents a subscript span of -text. The macro receives a single argument that corresponds to the subscript -span of text. This macro will only be produced, when the \Opt{subscripts} -option is enabled. +#### Table Renderer +The \mdef{markdownRendererTable} macro represents a table. This macro will only +be produced, when the \Opt{pipeTables} option is enabled. The macro receives the +parameters `{`\meta{caption}`}{`\meta{number of rows}`}{`\meta{number of columns}`}` +followed by `{`\meta{alignments}`}` and then by `{`\meta{row}`}` repeated +\meta{number of rows} times, where \meta{row} is `{`\meta{column}`}` repeated +\meta{number of columns} times, \meta{alignments} is \meta{alignment} repeated +\meta{number of columns} times, and \meta{alignment} is one of the following: + +- `d` -- The corresponding column has an unspecified (default) alignment. +- `l` -- The corresponding column is left-aligned. +- `c` -- The corresponding column is centered. +- `r` -- The corresponding column is right-aligned. + +% \end{markdown} +% +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[pipeTables, tableCaptions]{markdown} +\newcount\rowCounter +\newcount\columnCounter +\makeatletter +\def\processRow#1{% + \columnCounter=1% + \ifnum\rowCounter=0\relax + As for the alignment, + \else + In row \the\rowCounter, + \fi + \processColumn#1 + \advance\rowCounter by 1\relax + \ifnum\rowCounter>\rowTotal\relax + \expandafter\@gobble + \fi\processRow}% +\def\processColumn#1{% + column number \the\columnCounter{} + \ifnum\rowCounter=0\relax + \if#1d{}has default alignment\fi + \if#1l{}is left-aligned\fi + \if#1c{}is centered\fi + \if#1r{}is right-aligned\fi + \else + says \emph{#1}% + \fi + \advance\columnCounter by 1\relax + \ifnum\columnCounter<\columnTotal\relax, \fi + \ifnum\columnCounter=\columnTotal\relax, and \fi + \ifnum\columnCounter>\columnTotal\relax + .\expandafter\@gobble + \fi\processColumn}% +\makeatother +\markdownSetup{ + renderers = { + table = {% + This is a table with caption \emph{#1} that is #3 colums wide + and #2 rows long. + \rowCounter=0% + \def\rowTotal{#2}% + \def\columnTotal{#3}% + \processRow + }, + }, +} +\begin{document} +\begin{markdown} +| Right | Left | Default | Center | +|------:|:-----|---------|:------:| +| 12 | 12 | 12 | 12 | +| 123 | 123 | 123 | 123 | +| 1 | 1 | 1 | 1 | + + : Demonstration of pipe table syntax +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> This is a table with caption *Demonstration of pipe table syntax* that is 4 +> colums wide and 4 rows long. As for the alignment, column number 1 is +> right-aligned, column number 2 is left-aligned, column number 3 has default +> alignment, and column number 4 is centered. In row 1, column number 1 says +> *Right*, column number 2 says *Left*, column number 3 says *Default*, and +> column number 4 says *Center*. In row 2, column number 1 says *12*, column +> number 2 says *12*, column number 3 says *12*, and column number 4 says *12*. +> In row 3, column number 1 says *123*, column number 2 says *123*, column +> number 3 says *123*, and column number 4 says *123*. In row 4, column number +> 1 says *1*, column number 2 says *1*, column number 3 says *1*, and column +> number 4 says *1*. + + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererTable{% + \markdownRendererTablePrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { table } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { table } + { 3 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Text Citations Renderer +The \mdef{markdownRendererTextCite} macro represents a string of one or more +text citations. This macro will only be produced, when the +\Opt{citations} option is enabled. The macro receives parameters in the same +format as the \mref{markdownRendererCite} macro. + +% \end{markdown} +% +% \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[citations]{markdown} +\newcount\citationsCounter +\newcount\citationsTotal +\makeatletter +\def\citations#1#2#3#4{% + a text citation \emph{#4} + \advance\citationsCounter by 1\relax + \ifx\relax#2\relax + \ifx\relax#3\relax\else + with a postfix \emph{#3}% + \fi + \else + with a prefix \emph{#2}% + \ifx\relax#3\relax\else + \ and a postfix \emph{#3}% + \fi + \fi + \ifnum\citationsCounter>\citationsTotal\relax + .% + \expandafter\@gobble + \else + , and + \fi\citations} +\makeatother +\markdownSetup{ + renderers = { + textCite = {% + \citationsCounter=1% + \citationsTotal=#1% + This is + \expandafter\citations + }, + }, +} +\begin{document} +\begin{markdown} +@abrahams90 [pp. 12; also @eijkhout91] +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> This is a text citation *abrahams90* with a postfix *pp. 12*, +> and a citation *eijkhout91* with a prefix *also*. + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererTextCite{% + \markdownRendererTextCitePrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { textCite } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { textCite } + { 1 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Thematic Break Renderer +The \mdef{markdownRendererThematicBreak} macro represents a thematic break. +The macro receives no arguments. % \end{markdown} % @@ -15583,10 +15526,13 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \input markdown -\def\markdownOptionSubscripts{true} -\def\markdownRendererSubscript#1{ (#1 moles) and } +\def\markdownRendererThematicBreak{\vfil\break} \markdownBegin -H~2~O is a liquid. +This is the first page. + +*** + +This is the second page. \markdownEnd \bye ``````` @@ -15597,7 +15543,11 @@ luatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> H (2 moles) and O is a liquid. +> This is the first page. +> +> *** +> +> This is the second page. ##### \LaTeX{} Example {.unnumbered} @@ -15605,15 +15555,19 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \documentclass{article} -\usepackage[subscripts]{markdown} +\usepackage{markdown} \markdownSetup{ renderers = { - subscript = { (#1 moles) and }, + thematicBreak = \newpage, }, } \begin{document} \begin{markdown} -H~2~O is a liquid. +This is the first page. + +*** + +This is the second page. \end{markdown} \end{document} ``````` @@ -15624,7 +15578,11 @@ lualatex document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> H (2 moles) and O is a liquid. +> This is the first page. +> +> *** +> +> This is the second page. ##### \Hologo{ConTeXt} Example {.unnumbered} @@ -15632,11 +15590,14 @@ Using a text editor, create a text document named `document.tex` with the following content: ``` tex \usemodule[t][markdown] -\setupmarkdown[subscripts = yes] -\def\markdownRendererSubscript#1{ (#1 moles) and } +\def\markdownRendererThematicBreak{\page[yes]} \starttext \startmarkdown -H~2~O is a liquid. +This is the first page. + +*** + +This is the second page. \stopmarkdown \stoptext ``````` @@ -15647,23 +15608,68 @@ context document.tex A PDF document named `document.pdf` should be produced and contain the following text: -> H (2 moles) and O is a liquid. +> This is the first page. +> +> *** +> +> This is the second page. %</manual-tokens> %<*tex> % \fi +% \begin{markdown} % +% The \mdef{markdownRendererHorizontalRule} and +% \mdef{markdownRendererHorizontalRulePrototype} macros have been deprecated +% and will be removed in Markdown 3.0.0. +% +% \end{markdown} % \begin{macrocode} -\def\markdownRendererSubscript{% - \markdownRendererSubscriptPrototype}% \ExplSyntaxOn +\cs_new:Npn + \markdownRendererThematicBreak + { + \cs_if_exist:NTF + \markdownRendererHorizontalRule + { + \markdownWarning + { + Horizontal~rule~renderer~has~been~deprecated,~ + to~be~removed~in~Markdown~3.0.0 + } + \markdownRendererHorizontalRule + } + { + \cs_if_exist:NTF + \markdownRendererHorizontalRulePrototype + { + \markdownWarning + { + Horizontal~rule~renderer~prototype~has~been~deprecated,~ + to~be~removed~in~Markdown~3.0.0 + } + \markdownRendererHorizontalRulePrototype + } + { + \markdownRendererThematicBreakPrototype + } + } + } \seq_gput_right:Nn \g_@@_renderers_seq - { subscript } + { horizontalRule } \prop_gput:Nnn \g_@@_renderer_arities_prop - { subscript } - { 1 } + { horizontalRule } + { 0 } +\seq_gput_right:Nn + \g_@@_renderers_seq + { thematicBreak } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { thematicBreak } + { 0 } +\ExplSyntaxOff % \end{macrocode} % \par % @@ -15674,30 +15680,213 @@ following text: % % \begin{markdown} -#### Raw Content Renderers -The \mdef{markdownRendererInputRawInline} macro represents an inline raw span. -The macro receives two arguments: the filename of a file contaning the inline -raw span contents and the raw attribute that designates the format of the -inline raw span. This macro will only be produced, when the \Opt{rawAttribute} -option is enabled. +#### Tickbox Renderers +The macros named \mdef{markdownRendererTickedBox}, +\mdef{markdownRendererHalfTickedBox}, and \mdef{markdownRendererUntickedBox} +represent ticked and unticked boxes, respectively. These macros will either be +produced, when the \Opt{taskLists} option is enabled, or when the Ballot Box +with X (☒, U+2612), Hourglass (⌛, U+231B) or Ballot Box (☐, U+2610) Unicode +characters are encountered in the markdown input, respectively. % \end{markdown} % % \iffalse + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[taskLists]{markdown} +\markdownSetup{ + renderers = { + untickedBox = No, + tickedBox = Yes, + }, +} +\begin{document} +\begin{markdown} +- [ ] you can't. +- [x] I can! +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> - No you can't. +> - Yes I can! + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\setupmarkdown[taskLists = yes] +\def\markdownRendererUntickedBox{No} +\def\markdownRendererTickedBox{Yes} +\starttext +\startmarkdown +- [ ] you can't. +- [x] I can! +\stopmarkdown +\stoptext +```````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> - No you can't. +> - Yes I can! + %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererInputRawInline{% - \markdownRendererInputRawInlinePrototype}% +\def\markdownRendererTickedBox{% + \markdownRendererTickedBoxPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inputRawInline } + { tickedBox } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inputRawInline } + { tickedBox } + { 0 } +\ExplSyntaxOff +\def\markdownRendererHalfTickedBox{% + \markdownRendererHalfTickedBoxPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { halfTickedBox } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { halfTickedBox } + { 0 } +\ExplSyntaxOff +\def\markdownRendererUntickedBox{% + \markdownRendererUntickedBoxPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { untickedBox } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { untickedBox } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### YAML Metadata Renderers {#yamlmetadatarenderers} + +The \mdef{markdownRendererJekyllDataBegin} macro represents the beginning of a +\acro{yaml} document. This macro will only be produced when the \Opt{jekyllData} +option is enabled. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataBegin{% + \markdownRendererJekyllDataBeginPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataBegin } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataBegin } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataEnd} macro represents the end of a +\acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives no arguments. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataEnd{% + \markdownRendererJekyllDataEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataMappingBegin} macro represents the +beginning of a mapping in a \acro{yaml} document. This macro will only be +produced when the \Opt{jekyllData} option is enabled. The macro receives two +arguments: the scalar key in the parent structure, cast to a string following +\acro{yaml} serialization rules, and the number of items in the mapping. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataMappingBegin{% + \markdownRendererJekyllDataMappingBeginPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataMappingBegin } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataMappingBegin } { 2 } \ExplSyntaxOff % \end{macrocode} @@ -15710,76 +15899,130 @@ option is enabled. % % \begin{markdown} -The \mdef{markdownRendererInputRawBlock} macro represents a raw block. The -macro receives two arguments: the filename of a file contaning the raw block -and the raw attribute that designates the format of the raw block. This macro -will only be produced, when the \Opt{rawAttribute} and \Opt{fencedCode} options -are enabled. +The \mdef{markdownRendererJekyllDataMappingEnd} macro represents the +end of a mapping in a \acro{yaml} document. This macro will only be produced +when the \Opt{jekyllData} option is enabled. The macro receives no arguments. % \end{markdown} % % \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataMappingEnd{% + \markdownRendererJekyllDataMappingEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataMappingEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataMappingEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -##### \LaTeX{} Example {.unnumbered} +The \mdef{markdownRendererJekyllDataSequenceBegin} macro represents the +beginning of a sequence in a \acro{yaml} document. This macro will only be +produced when the \Opt{jekyllData} option is enabled. The macro receives two +arguments: the scalar key in the parent structure, cast to a string following +\acro{yaml} serialization rules, and the number of items in the sequence. -Using a text editor, create a text document named `document.tex` with the -following content: -```` tex -\documentclass{article} -\usepackage[rawAttribute, fencedCode]{markdown} -\usepackage{expl3} +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataSequenceBegin{% + \markdownRendererJekyllDataSequenceBeginPrototype}% \ExplSyntaxOn -\cs_new:Nn - \display_raw_content:nn - { - % If the raw attribute is TeX, execute the content as a TeX document. - \str_if_eq:nnTF - { #2 } - { tex } - { \markdownEscape { #1 } } - % Otherwise, ignore the content. - { } - } -\markdownSetup{ - renderers = { - rawInline = { \display_raw_content:nn { #1 } { #2 } }, - rawBlock = { \display_raw_content:nn { #1 } { #2 } } - }, -} +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataSequenceBegin } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataSequenceBegin } + { 2 } \ExplSyntaxOff -\begin{document} -\begin{markdown} -`$H_2 O$`{=tex} is a liquid. +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} -``` {=html} -<p>Here is some HTML content that will be ignored.</p> -``` -\end{markdown} -\end{document} -```` -Next, invoke LuaTeX from the terminal: -``` sh -lualatex document.tex -`````` -A PDF document named `document.pdf` should be produced and contain the -following text: +The \mdef{markdownRendererJekyllDataSequenceEnd} macro represents the +end of a sequence in a \acro{yaml} document. This macro will only be produced +when the \Opt{jekyllData} option is enabled. The macro receives no arguments. -> H~2~O is a liquid. +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataSequenceEnd{% + \markdownRendererJekyllDataSequenceEndPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataSequenceEnd } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataSequenceEnd } + { 0 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} +The \mdef{markdownRendererJekyllDataBoolean} macro represents a boolean scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, and the scalar value, both cast to a string +following \acro{yaml} serialization rules. + +% \end{markdown} +% +% \iffalse %</manual-tokens> %<*tex> % \fi % % \begin{macrocode} -\def\markdownRendererInputRawBlock{% - \markdownRendererInputRawBlockPrototype}% +\def\markdownRendererJekyllDataBoolean{% + \markdownRendererJekyllDataBooleanPrototype}% \ExplSyntaxOn \seq_gput_right:Nn \g_@@_renderers_seq - { inputRawBlock } + { jekyllDataBoolean } \prop_gput:Nnn \g_@@_renderer_arities_prop - { inputRawBlock } + { jekyllDataBoolean } { 2 } \ExplSyntaxOff % \end{macrocode} @@ -15792,6 +16035,209 @@ following text: % % \begin{markdown} +The \mdef{markdownRendererJekyllDataNumber} macro represents a numeric scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, and the scalar value, both cast to a string +following \acro{yaml} serialization rules. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataNumber{% + \markdownRendererJekyllDataNumberPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataNumber } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataNumber } + { 2 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataString} macro represents a string scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives two arguments: the +scalar key in the parent structure, cast to a string following \acro{yaml} +serialization rules, and the scalar value. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataString{% + \markdownRendererJekyllDataStringPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataString } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataString } + { 2 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +The \mdef{markdownRendererJekyllDataEmpty} macro represents an empty scalar +value in a \acro{yaml} document. This macro will only be produced when the +\Opt{jekyllData} option is enabled. The macro receives one argument: the +scalar key in the parent structure, cast to a string following \acro{yaml} +serialization rules. + +% See also Section <#sec:expl3yamlmetadata> for the description of the +% high-level expl3 interface that you can also use to react to \acro{yaml} +% metadata. +% +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataEmpty{% + \markdownRendererJekyllDataEmptyPrototype}% +\ExplSyntaxOn +\seq_gput_right:Nn + \g_@@_renderers_seq + { jekyllDataEmpty } +\prop_gput:Nnn + \g_@@_renderer_arities_prop + { jekyllDataEmpty } + { 1 } +\ExplSyntaxOff +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> + +##### Plain \TeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionJekyllData{true} +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\markdownBegin +--- +name: Jane Doe +age: 99 +--- +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +##### \LaTeX{} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[jekyllData]{markdown} +\markdownSetup{ + renderers = { + jekyllDataString = {\gdef\name{#2}}, + jekyllDataNumber = {\gdef\age{#2}}, + jekyllDataEnd = {\name{} is \age{} years old.}, + } +} +\begin{document} + +\begin{markdown} +--- +name: Jane Doe +age: 99 +--- +\end{markdown} + +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +##### \Hologo{ConTeXt} Example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\setupmarkdown[jekyllData = yes] +\def\markdownRendererJekyllDataString#1#2{\gdef\name{#2}} +\def\markdownRendererJekyllDataNumber#1#2{\gdef\age{#2}} +\def\markdownRendererJekyllDataEnd{% + \name{} is \age{} years old.} +\starttext + +\startmarkdown +--- +name: Jane Doe +age: 99 +--- +\stopmarkdown + +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Jane Doe is 99 years old. + +% \fi +% +% \begin{markdown} + ### Token Renderer Prototypes {#texrendererprototypes} % \end{markdown} @@ -16056,8 +16502,8 @@ following text: % \end{macrocode} % \begin{markdown} % -% The \mdef{markdownRendererFootnote} and -% \mdef{markdownRendererFootnotePrototype} macros have been deprecated +% The \mref{markdownRendererFootnote} and +% \mref{markdownRendererFootnotePrototype} macros have been deprecated % and will be removed in Markdown 3.0.0. % % \end{markdown} @@ -16067,8 +16513,8 @@ following text: % \end{macrocode} % \begin{markdown} % -% The \mdef{markdownRendererHorizontalRule} and -% \mdef{markdownRendererHorizontalRulePrototype} macros have been deprecated +% The \mref{markdownRendererHorizontalRule} and +% \mref{markdownRendererHorizontalRulePrototype} macros have been deprecated % and will be removed in Markdown 3.0.0. % % \end{markdown} @@ -16181,7 +16627,7 @@ following text: % as follows: % % - `0` – Shell escape via the 18 output file stream -% - `1` – Shell escape via the Lua \luamref{os.execute} method +% - `1` – Shell escape via the Lua `os.execute` method % - `2` – Direct Lua access % - `3` – The \pkg{lt3luabridge} Lua package % @@ -16223,6 +16669,7 @@ following text: } } } +\ExplSyntaxOff % \end{macrocode} % \par % \begin{markdown} @@ -16307,8 +16754,8 @@ pdflatex --shell-escape document.tex % Section <#sec:texinterface>). % % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section <#sec:texinterfacelogging>) to use the \LaTeX{} \mref{PackageInfo}, -% \mref{PackageWarning}, and \mref{PackageError} macros. +% Section <#sec:texinterfacelogging>) to use the \LaTeX{} `\PackageInfo`, +% `\PackageWarning`, and `\PackageError` macros. % % \end{markdown} % \begin{macrocode} @@ -16327,7 +16774,7 @@ pdflatex --shell-escape document.tex % \end{Verbatim} % \begin{markdown} % where \meta{options} are the \LaTeX{} interface options (see Section -% <#sec:latexoptions>). Note that \meta{options} inside the \mref{usepackage} +% <#sec:latexoptions>). Note that \meta{options} inside the `\usepackage` % macro may not set the `markdownRenderers` (see Section % <#sec:latexrenderers>) and `markdownRendererPrototypes` (see Section % <#sec:latexrendererprototypes>) keys. This limitation is due to the way @@ -16354,8 +16801,8 @@ pdflatex --shell-escape document.tex % \end{macrocode} % \markdownBegin % -% You may prepend your own code to the \mref{markdown} macro and append your own -% code to the \mref{endmarkdown} macro to produce special effects before and after +% You may prepend your own code to the \mdef{markdown} macro and append your own +% code to the \mdef{endmarkdown} macro to produce special effects before and after % the \envmref{markdown} \LaTeX{} environment (and likewise for the starred % version). % @@ -16597,7 +17044,7 @@ without low-level programming. % *name* is *qualified* and contains no underscores, and a value is qualified % if and only if it contains at least one forward slash. Themes are inspired by % the Beamer \LaTeX{} package, which provides similar functionality with its -% \mref{usetheme} macro [@tantau21, Section 15.1]. +% `\usetheme` macro [@tantau21, Section 15.1]. % % Theme names must be qualified to minimize naming conflicts between different % themes intended for a single \LaTeX{} document class or for a single \LaTeX{} @@ -16615,7 +17062,7 @@ without low-level programming. % package named `markdownthemewitiko_beamer_MU.sty`. % % If the \LaTeX{} option with key `theme` is (repeatedly) specified in the -% \mref{usepackage} macro, the loading of the theme(s) will be postponed in +% `\usepackage` macro, the loading of the theme(s) will be postponed in % first-in-first-out order until after the Markdown \LaTeX{} package has been % loaded. Otherwise, the theme(s) will be loaded immediately. For example, % there is a theme named `witiko/dot`, which typesets fenced code blocks with @@ -16796,7 +17243,7 @@ Example themes provided with the Markdown package include: % ``` The theme requires a Unix-like operating system with GNU Diffutils and Graphviz installed. The theme also requires shell access unless the - \mref{markdownOptionFrozenCache} plain \TeX{} option is enabled. + \Opt{frozenCache} plain \TeX{} option is enabled. % \markdownEnd % \iffalse @@ -16889,7 +17336,7 @@ conference article: The theme requires the \pkg{catchfile} \LaTeX{} package and a Unix-like operating system with GNU Coreutils `md5sum` and either GNU Wget or cURL installed. The theme also requires shell access unless the - \mref{markdownOptionFrozenCache} plain \TeX{} option is enabled. + \Opt{frozenCache} plain \TeX{} option is enabled. % \markdownEnd % \iffalse @@ -17231,7 +17678,7 @@ The following ordered list will be preceded by roman numerals: % \par % \begin{markdown} % -% The \mref{markdownOptionFinalizeCache} and \mref{markdownOptionFrozenCache} plain +% The \Opt{finalizeCache} and \Opt{frozenCache} plain % \TeX{} options are exposed through \LaTeX{} options with keys `finalizeCache` % and `frozenCache`. % @@ -17263,8 +17710,8 @@ The following ordered list will be preceded by roman numerals: % \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of -% plain \TeX{} interface options \mref{markdownOptionHybrid}, -% \mref{markdownOptionSmartEllipses}, and \mref{markdownOptionCacheDir}. +% plain \TeX{} interface options \Opt{hybrid}, \Opt{smartEllipses}, and +% \Opt{cacheDir}. % ``` tex % \markdownSetup{ % hybrid, @@ -17411,7 +17858,7 @@ The following ordered list will be preceded by roman numerals: % \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of the -% \mref{markdownRendererImagePrototype} and \mref{markdownRendererCodeSpanPrototype} +% `\markdownRendererImagePrototype` and `\markdownRendererCodeSpanPrototype` % markdown token renderer prototypes. % ``` tex % \markdownSetup{ @@ -17498,7 +17945,7 @@ texexec --passon=--shell-escape document.tex % % The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros % (see Section <#sec:texinterfacelogging>) to use the \Hologo{ConTeXt} -% \mref{writestatus} macro. +% `\writestatus` macro. % % \end{markdown} % \begin{macrocode} @@ -17517,7 +17964,7 @@ texexec --passon=--shell-escape document.tex % \usemodule[t][markdown] % ``````` % \noindent It is expected that the special plain \TeX{} characters have the -% expected category codes, when \mref{input}ting the file. +% expected category codes, when `\input`ting the file. % %### Typesetting Markdown % The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro @@ -20402,7 +20849,6 @@ function M.writer.new(options) self.escaped_uri_chars = { ["{"] = "\\markdownRendererLeftBrace{}", ["}"] = "\\markdownRendererRightBrace{}", - ["%"] = "\\markdownRendererPercentSign{}", ["\\"] = "\\markdownRendererBackslash{}", } self.escaped_minimal_strings = { @@ -20759,9 +21205,39 @@ function M.writer.new(options) % \par % \begin{markdown} % +% Define \luamdef{writer->attributes} as a function that will transform +% input attributes `attr` to the output format. +% +% \end{markdown} +% \begin{macrocode} + function self.attributes(attr) + local buf = {} + + table.sort(attr) + local key, value + for i = 1, #attr do + if attr[i]:sub(1, 1) == "#" then + table.insert(buf, {"\\markdownRendererAttributeIdentifier{", + attr[i]:sub(2), "}"}) + elseif attr[i]:sub(1, 1) == "." then + table.insert(buf, {"\\markdownRendererAttributeClassName{", + attr[i]:sub(2), "}"}) + else + key, value = attr[i]:match("([^= ]+)%s*=%s*(.*)") + table.insert(buf, {"\\markdownRendererAttributeKeyValue{", + key, "}{", value, "}"}) + end + end + + return buf + end +% \end{macrocode} +% \par +% \begin{markdown} +% % Define \luamdef{writer->active\_attributes} as a stack of attributes % of the headings that are currently active. The -% \luamref{writer->active\_headings} member variable is mutable. +% \luamdef{writer->active\_headings} member variable is mutable. % % \end{markdown} % \begin{macrocode} @@ -20771,7 +21247,7 @@ function M.writer.new(options) % \begin{markdown} % % Define \luamdef{writer->heading} as a function that will transform an -% input heading `s` at level `level` with identifiers `identifiers` to the +% input heading `s` at level `level` with attributes `attributes` to the % output format. % % \end{markdown} @@ -20853,21 +21329,7 @@ function M.writer.new(options) end if self.is_writing then - table.sort(attributes) - local key, value - for i = 1, #attributes do - if attributes[i]:sub(1, 1) == "#" then - table.insert(buf, {"\\markdownRendererAttributeIdentifier{", - attributes[i]:sub(2), "}"}) - elseif attributes[i]:sub(1, 1) == "." then - table.insert(buf, {"\\markdownRendererAttributeClassName{", - attributes[i]:sub(2), "}"}) - else - key, value = attributes[i]:match("([^= ]+)%s*=%s*(.*)") - table.insert(buf, {"\\markdownRendererAttributeKeyValue{", - key, "}{", value, "}"}) - end - end + table.insert(buf, self.attributes(attributes)) end local cmd @@ -21015,7 +21477,8 @@ parsers.doubletildes = P("~~") parsers.fourspaces = P(" ") parsers.any = P(1) -parsers.fail = parsers.any - 1 +parsers.succeed = P(true) +parsers.fail = P(false) parsers.escapable = S("!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~") parsers.anyescaped = parsers.backslash / "" * parsers.escapable @@ -21232,14 +21695,31 @@ local function captures_geq_length(_,i,a,b) return #a >= #b and i end -parsers.infostring = (parsers.linechar - (parsers.backtick - + parsers.space^1 * (parsers.newline + parsers.eof)))^0 +parsers.tilde_infostring + = C((parsers.linechar + - (parsers.spacechar^1 * parsers.newline))^0) + * parsers.optionalspace + * (parsers.newline + parsers.eof) + +parsers.backtick_infostring + = C((parsers.linechar + - (parsers.backtick + + parsers.spacechar^1 * parsers.newline))^0) + * parsers.optionalspace + * (parsers.newline + parsers.eof) local fenceindent -parsers.fencehead = function(char) +parsers.fencehead = function(char, infostring) + return C(parsers.nonindentspace) / function(s) fenceindent = #s end + * Cg(char^3, "fencelength") + * parsers.optionalspace * infostring +end + +parsers.fencehead_with_attributes + = function(char) return C(parsers.nonindentspace) / function(s) fenceindent = #s end * Cg(char^3, "fencelength") - * parsers.optionalspace * C(parsers.infostring) + * parsers.optionalspace * Ct(parsers.attributes) * parsers.optionalspace * (parsers.newline + parsers.eof) end @@ -21503,12 +21983,14 @@ parsers.urlchar = parsers.anyescaped - parsers.newline - parsers.more % \end{markdown} % \begin{macrocode} parsers.TildeFencedCode - = parsers.fencehead(parsers.tilde) + = parsers.fencehead(parsers.tilde, + parsers.tilde_infostring) * Cs(parsers.fencedline(parsers.tilde)^0) * parsers.fencetail(parsers.tilde) parsers.BacktickFencedCode - = parsers.fencehead(parsers.backtick) + = parsers.fencehead(parsers.backtick, + parsers.backtick_infostring) * Cs(parsers.fencedline(parsers.backtick)^0) * parsers.fencetail(parsers.backtick) @@ -21578,7 +22060,7 @@ function M.reader.new(writer, options) % \begin{markdown} % % Create a \luamdef{reader->parsers} hash table that stores \acro{peg} patterns -% that depend on the received `options`. Make \luamdef{reader->parsers} inherit +% that depend on the received `options`. Make \luamref{reader->parsers} inherit % from the global \luamref{parsers} table. % % \end{markdown} @@ -21804,14 +22286,6 @@ function M.reader.new(writer, options) % \par % \begin{markdown} % -%#### Parsers Used for Notes (local) -% -% \end{markdown} -% \begin{macrocode} -% \end{macrocode} -% \par -% \begin{markdown} -% %#### Helpers for Links and References (local) % % \end{markdown} @@ -22220,7 +22694,7 @@ function M.reader.new(writer, options) % \begin{markdown} % % Create a local writable copy of the global read-only -% \luamdef{walkable_syntax} hash table. This table can be used by user-defined +% \luamref{walkable_syntax} hash table. This table can be used by user-defined % syntax extensions to insert new \acro{peg} patterns into existing rules % of the \acro{peg} grammar of markdown using % the \luamref{reader->insert_pattern} method. Furthermore, built-in syntax @@ -22300,12 +22774,12 @@ function M.reader.new(writer, options) local syntax = { "Blocks", - Blocks = ( V("ExpectedJekyllData") - * (V("Blank")^0 / writer.interblocksep) - )^-1 + Blocks = V("InitializeState") + * ( V("ExpectedJekyllData") + * (V("Blank")^0 / writer.interblocksep))^-1 * V("Blank")^0 * V("Block")^-1 - * (V("Blank")^0 / writer.interblocksep + * ( V("Blank")^0 / writer.interblocksep * V("Block"))^0 * V("Blank")^0 * parsers.eof, @@ -22344,23 +22818,37 @@ function M.reader.new(writer, options) Smart = parsers.Smart, Symbol = parsers.Symbol, SpecialChar = parsers.fail, + InitializeState = parsers.succeed, } % \end{macrocode} % \par % \begin{markdown} % % Define \luamref{reader->update_rule} as a function that receives two -% arguments: a left-hand side terminal symbol and a \acro{peg} pattern. -% The function (re)defines \luamref{walkable_syntax}`[`left-hand side terminal -% symbol`]` to be equal to pattern. +% arguments: a left-hand side terminal symbol and a function that accepts +% the current \acro{peg} pattern in \luamref{walkable_syntax}`[`left-hand side +% terminal symbol`]` if defined or `nil` otherwise and returns a +% \acro{peg} pattern that will (re)define \luamref{walkable_syntax}`[`left-hand +% side terminal symbol`]`. % % \end{markdown} % \begin{macrocode} - self.update_rule = function(rule_name, pattern) + self.update_rule = function(rule_name, get_pattern) assert(current_extension_name ~= nil) assert(syntax[rule_name] ~= nil, [[Rule ]] .. rule_name .. [[ -> ... does not exist in markdown grammar]]) - local accountable_pattern = { pattern, current_extension_name, rule_name } + local previous_pattern + local extension_name + if walkable_syntax[rule_name] then + local previous_accountable_pattern = walkable_syntax[rule_name][1] + previous_pattern = previous_accountable_pattern[1] + extension_name = previous_accountable_pattern[2] .. ", " .. current_extension_name + else + previous_pattern = nil + extension_name = current_extension_name + end + local pattern = get_pattern(previous_pattern) + local accountable_pattern = { pattern, extension_name, rule_name } walkable_syntax[rule_name] = { accountable_pattern } end % \end{macrocode} @@ -22390,6 +22878,19 @@ function M.reader.new(writer, options) % \par % \begin{markdown} % +% Add method \luamdef{reader->initialize_named_group} that defines named groups +% with a default capture value. +% +% \end{markdown} +% \begin{macrocode} + self.initialize_named_group = function(name, value) + syntax.InitializeState = syntax.InitializeState + * Cg(Ct("") / value, name) + end +% \end{macrocode} +% \par +% \begin{markdown} +% % Apply syntax extensions. % % \end{markdown} @@ -22556,7 +23057,10 @@ function M.reader.new(writer, options) local inlines_t = util.table_copy(syntax) inlines_t[1] = "Inlines" - inlines_t.Inlines = parsers.Inline^0 * (parsers.spacing^0 * parsers.eof / "") + inlines_t.Inlines = V("InitializeState") + * parsers.Inline^0 + * ( parsers.spacing^0 + * parsers.eof / "") parsers.inlines = Ct(inlines_t) local inlines_no_link_t = util.table_copy(inlines_t) @@ -22665,7 +23169,7 @@ end % %### Built-In Syntax Extensions {#luabuiltinextensions} % -% Create \luamdef{extensions} hash table that contains built-in syntax +% Create \luamref{extensions} hash table that contains built-in syntax % extensions. Syntax extensions are functions that produce objects with two % methods: `extend_writer` and `extend_reader`. The `extend_writer` object % takes a \luamref{writer} object as the only parameter and mutates it. @@ -22678,6 +23182,50 @@ M.extensions = {} % \end{macrocode} % \begin{markdown} % +%#### Bracketed Spans +% +% The \luamdef{extensions.bracketed_spans} function implements the Pandoc +% bracketed spans syntax extension. +% +% \end{markdown} +% \begin{macrocode} +M.extensions.bracketed_spans = function() + return { + name = "built-in bracketed_spans syntax extension", + extend_writer = function(self) +% \end{macrocode} +% \par +% \begin{markdown} +% +% Define \luamdef{writer->span} as a function that will transform an input +% bracketed span `s` with attributes `attr` to the output format. +% +% \end{markdown} +% \begin{macrocode} + function self.span(s, attr) + return {"\\markdownRendererBracketedSpanAttributeContextBegin", + self.attributes(attr), + s, + "\\markdownRendererBracketedSpanAttributeContextEnd{}"} + end + end, extend_reader = function(self) + local parsers = self.parsers + local writer = self.writer + + local Span = parsers.between(parsers.Inline, + parsers.lbracket, + parsers.rbracket) + * Ct(parsers.attributes) + / writer.span + + self.insert_pattern("Inline after Emph", + Span, "Span") + end + } +end +% \end{macrocode} +% \begin{markdown} +% %#### Citations % % The \luamdef{extensions.citations} function implements the Pandoc citation @@ -22726,7 +23274,7 @@ M.extensions.citations = function(citation_nbsps) % \begin{markdown} % % Define \luamdef{writer->citation} as a function that will transform an input -% citation name `c` to the output format. If \luamref{writer->hybrid} is `true`, +% citation name `c` to the output format. If option \Opt{hybrid} is enabled, % use the \luamref{writer->escape_minimal} function. Otherwise, use the % \luamref{escape_citation} function. % @@ -23052,9 +23600,9 @@ end % %#### Definition Lists % -% The \luamdef{extensions.definition_lists} function implements the definition -% list syntax extension. If the `tight_lists` parameter is `true`, tight lists -% will produce special right item renderers. +% The \luamdef{extensions.definition_lists} function implements the Pandoc +% definition list syntax extension. If the `tight_lists` parameter is `true`, +% tight lists will produce special right item renderers. % % \end{markdown} % \begin{macrocode} @@ -23150,12 +23698,213 @@ end % \end{macrocode} % \begin{markdown} % +%#### Fancy Lists +% +% The \luamdef{extensions.fancy_lists} function implements the Pandoc fancy +% list syntax extension. +% +% \end{markdown} +% \begin{macrocode} +M.extensions.fancy_lists = function() + return { + name = "built-in fancy_lists syntax extension", + extend_writer = function(self) + local options = self.options + +% \end{macrocode} +% \par +% \begin{markdown} +% +% Define \luamdef{writer->fancylist} as a function that will transform an +% input ordered list to the output format, where: +% +%- `items` is an array of the list items, +%- `tight` specifies, whether the list is tight or not, +%- `startnum` is the number of the first list item, +%- `numstyle` is the style of the list item labels from among the following: +% - `Decimal` -- decimal arabic numbers, +% - `LowerRoman` -- lower roman numbers, +% - `UpperRoman` -- upper roman numbers, +% - `LowerAlpha` -- lower ASCII alphabetic characters, and +% - `UpperAlpha` -- upper ASCII alphabetic characters, and +%- `numdelim` is the style of delimiters between list item labels and +% texts from among the following: +% - `Default` -- default style, +% - `OneParen` -- parentheses, and +% - `Period` -- periods. +% +% \end{markdown} +% \begin{macrocode} + function self.fancylist(items,tight,startnum,numstyle,numdelim) + if not self.is_writing then return "" end + local buffer = {} + local num = startnum + for _,item in ipairs(items) do + buffer[#buffer + 1] = self.fancyitem(item,num) + if num ~= nil then + num = num + 1 + end + end + local contents = util.intersperse(buffer,"\n") + if tight and options.tightLists then + return {"\\markdownRendererFancyOlBeginTight{", + numstyle,"}{",numdelim,"}",contents, + "\n\\markdownRendererFancyOlEndTight "} + else + return {"\\markdownRendererFancyOlBegin{", + numstyle,"}{",numdelim,"}",contents, + "\n\\markdownRendererFancyOlEnd "} + end + end +% \end{macrocode} +% \begin{markdown} +% +% Define \luamdef{writer->fancyitem} as a function that will transform an +% input fancy ordered list item to the output format, where `s` is the text of +% the list item. If the optional parameter `num` is present, it is the number +% of the list item. +% +% \end{markdown} +% \begin{macrocode} + function self.fancyitem(s,num) + if num ~= nil then + return {"\\markdownRendererFancyOlItemWithNumber{",num,"}",s, + "\\markdownRendererFancyOlItemEnd "} + else + return {"\\markdownRendererFancyOlItem ",s,"\\markdownRendererFancyOlItemEnd "} + end + end + end, extend_reader = function(self) + local parsers = self.parsers + local options = self.options + local writer = self.writer + + local label = parsers.dig + parsers.letter + local numdelim = parsers.period + parsers.rparent + local enumerator = C(label^3 * numdelim) * #parsers.spacing + + C(label^2 * numdelim) * #parsers.spacing + * (parsers.tab + parsers.space^1) + + C(label * numdelim) * #parsers.spacing + * (parsers.tab + parsers.space^-2) + + parsers.space * C(label^2 * numdelim) + * #parsers.spacing + + parsers.space * C(label * numdelim) + * #parsers.spacing + * (parsers.tab + parsers.space^-1) + + parsers.space * parsers.space * C(label^1 + * numdelim) * #parsers.spacing + local starter = parsers.bullet + enumerator + + local NestedList = Cs((parsers.optionallyindentedline + - starter)^1) + / function(a) return "\001"..a end + + local ListBlockLine = parsers.optionallyindentedline + - parsers.blankline - (parsers.indent^-1 + * starter) + + local ListBlock = parsers.line * ListBlockLine^0 + + local ListContinuationBlock = parsers.blanklines * (parsers.indent / "") + * ListBlock + + local TightListItem = function(starter) + return -parsers.ThematicBreak + * (Cs(starter / "" * parsers.tickbox^-1 * ListBlock * NestedList^-1) + / self.parser_functions.parse_blocks_nested) + * -(parsers.blanklines * parsers.indent) + end + + local LooseListItem = function(starter) + return -parsers.ThematicBreak + * Cs( starter / "" * parsers.tickbox^-1 * ListBlock * Cc("\n") + * (NestedList + ListContinuationBlock^0) + * (parsers.blanklines / "\n\n") + ) / self.parser_functions.parse_blocks_nested + end + + local function roman2number(roman) + local romans = { ["L"] = 50, ["X"] = 10, ["V"] = 5, ["I"] = 1 } + local numeral = 0 + + local i = 1 + local len = string.len(roman) + while i < len do + local z1, z2 = romans[ string.sub(roman, i, i) ], romans[ string.sub(roman, i+1, i+1) ] + if z1 < z2 then + numeral = numeral + (z2 - z1) + i = i + 2 + else + numeral = numeral + z1 + i = i + 1 + end + end + if i <= len then numeral = numeral + romans[ string.sub(roman,i,i) ] end + return numeral + end + + local function sniffstyle(itemprefix) + local numstr, delimend = itemprefix:match("^([A-Za-z0-9]*)([.)]*)") + local numdelim + if delimend == ")" then + numdelim = "OneParen" + elseif delimend == "." then + numdelim = "Period" + else + numdelim = "Default" + end + numstr = numstr or itemprefix + + local num + num = numstr:match("^([IVXL]+)") + if num then + return roman2number(num), "UpperRoman", numdelim + end + num = numstr:match("^([ivxl]+)") + if num then + return roman2number(string.upper(num)), "LowerRoman", numdelim + end + num = numstr:match("^([A-Z])") + if num then + return string.byte(num) - string.byte("A") + 1, "UpperAlpha", numdelim + end + num = numstr:match("^([a-z])") + if num then + return string.byte(num) - string.byte("a") + 1, "LowerAlpha", numdelim + end + return math.floor(tonumber(numstr) or 1), "Decimal", numdelim + end + + local function fancylist(items,tight,start) + local startnum, numstyle, numdelim = sniffstyle(start) + return writer.fancylist(items,tight, + options.startNumber and startnum, + numstyle or "Decimal", + numdelim or "Default") + end + + local FancyList = Cg(enumerator, "listtype") * + ( Ct(TightListItem(Cb("listtype")) + * TightListItem(enumerator)^0) + * Cc(true) * parsers.skipblanklines * -enumerator + + Ct(LooseListItem(Cb("listtype")) + * LooseListItem(enumerator)^0) + * Cc(false) * parsers.skipblanklines + ) * Cb("listtype") / fancylist + + self.update_rule("OrderedList", function() return FancyList end) + end + } +end +% \end{macrocode} +% \begin{markdown} +% %#### Fenced Code % % The \luamdef{extensions.fenced_code} function implements the commonmark % fenced code block syntax extension. When the `blank_before_code_fence` -% parameter is `true`, the syntax extension requires between a paragraph and -% the following fenced code block. +% parameter is `true`, the syntax extension requires a blank line between a +% paragraph and the following fenced code block. % % \end{markdown} % \begin{macrocode} @@ -23186,12 +23935,12 @@ M.extensions.fenced_code = function(blank_before_code_fence) local writer = self.writer local FencedCode = (parsers.TildeFencedCode - + parsers.BacktickFencedCode) - / function(infostring, code) - local expanded_code = self.expandtabs(code) - return writer.fencedCode(expanded_code, - infostring) - end + + parsers.BacktickFencedCode) + / function(infostring, code) + local expanded_code = self.expandtabs(code) + return writer.fencedCode(expanded_code, + infostring) + end self.insert_pattern("Block after Verbatim", FencedCode, "FencedCode") @@ -23200,12 +23949,18 @@ M.extensions.fenced_code = function(blank_before_code_fence) if blank_before_code_fence then fencestart = parsers.fail else - fencestart = parsers.fencehead(parsers.backtick) - + parsers.fencehead(parsers.tilde) + fencestart = parsers.fencehead(parsers.backtick, + parsers.backtick_infostring) + + parsers.fencehead(parsers.tilde, + parsers.tilde_infostring) end - local EndlineExceptions = parsers.EndlineExceptions + fencestart - self.update_rule("EndlineExceptions", EndlineExceptions) + self.update_rule("EndlineExceptions", function(previous_pattern) + if previous_pattern == nil then + previous_pattern = parsers.EndlineExceptions + end + return previous_pattern + fencestart + end) self.add_special_character("~") end @@ -23214,91 +23969,133 @@ end % \end{macrocode} % \begin{markdown} % -%#### Notes +%#### Fenced Divs % -% The \luamdef{extensions.notes} function implements the Pandoc note -% and inline note syntax extensions. When the `note` parameter is -% `true`, the Pandoc note syntax extension will be enabled. When the -% `inline_notes` parameter is `true`, the Pandoc inline note syntax -% extension will be enabled. +% The \luamdef{extensions.fenced_divs} function implements the Pandoc fenced +% divs syntax extension. When the `blank_before_div_fence` parameter is `true`, +% the syntax extension requires a blank line between a paragraph and the +% following fenced code block. % % \end{markdown} % \begin{macrocode} -M.extensions.notes = function(notes, inline_notes) - assert(notes or inline_notes) +M.extensions.fenced_divs = function(blank_before_div_fence) return { - name = "built-in notes syntax extension", + name = "built-in fenced_divs syntax extension", extend_writer = function(self) % \end{macrocode} % \par % \begin{markdown} % -% Define \luamdef{writer->note} as a function that will transform an -% input note `s` to the output format. +% Define \luamdef{writer->div} as a function that will transform an input +% fenced div with content `c` and with attributes `attr` to the output format. % % \end{markdown} % \begin{macrocode} - function self.note(s) - return {"\\markdownRendererNote{",s,"}"} + function self.div(c, attr) + return {"\\markdownRendererFencedDivAttributeContextBegin", + self.attributes(attr), + c, + "\\markdownRendererFencedDivAttributeContextEnd"} end end, extend_reader = function(self) local parsers = self.parsers local writer = self.writer +% \end{macrocode} +% \par +% \begin{markdown} +% +% Define basic patterns for matching the opening and the closing tag of a div. +% +% \end{markdown} +% \begin{macrocode} + local fenced_div_infostring + = C((parsers.linechar + - ( parsers.spacechar^1 + * parsers.colon^1))^1) - if inline_notes then - local InlineNote - = parsers.circumflex - * (parsers.tag / self.parser_functions.parse_inlines_no_inline_note) - / writer.note - - self.insert_pattern("Inline after Emph", - InlineNote, "InlineNote") - end - if notes then - local function strip_first_char(s) - return s:sub(2) - end - - local RawNoteRef - = #(parsers.lbracket * parsers.circumflex) - * parsers.tag / strip_first_char + local fenced_div_begin = parsers.nonindentspace + * parsers.colon^3 + * parsers.optionalspace + * fenced_div_infostring + * ( parsers.spacechar^1 + * parsers.colon^1)^0 + * parsers.optionalspace + * (parsers.newline + parsers.eof) - local rawnotes = {} + local fenced_div_end = parsers.nonindentspace + * parsers.colon^3 + * parsers.optionalspace + * (parsers.newline + parsers.eof) +% \end{macrocode} +% \par +% \begin{markdown} +% +% Initialize a named group named `div_level` for tracking how deep we are +% nested in divs. +% +% \end{markdown} +% \begin{macrocode} + self.initialize_named_group("div_level", "0") - -- like indirect_link - local function lookup_note(ref) - return writer.defer_call(function() - local found = rawnotes[self.normalize_tag(ref)] - if found then - return writer.note( - self.parser_functions.parse_blocks_nested(found)) - else - return {"[", - self.parser_functions.parse_inlines("^" .. ref), "]"} - end - end) + local function increment_div_level(increment) + local function update_div_level(s, i, current_level) -- luacheck: ignore s i + current_level = tonumber(current_level) + local next_level = tostring(current_level + increment) + return true, next_level end - local function register_note(ref,rawnote) - rawnotes[self.normalize_tag(ref)] = rawnote - return "" - end + return Cg( Cmt(Cb("div_level"), update_div_level) + , "div_level") + end - local NoteRef = RawNoteRef / lookup_note + local FencedDiv = fenced_div_begin * increment_div_level(1) + * parsers.skipblanklines + * Ct( (V("Block") - fenced_div_end)^-1 + * ( parsers.blanklines + / function() + return writer.interblocksep + end + * (V("Block") - fenced_div_end))^0) + * parsers.skipblanklines + * fenced_div_end * increment_div_level(-1) + / function (infostring, div) + local attr = lpeg.match(Ct(parsers.attributes), infostring) + if attr == nil then + attr = {"." .. infostring} + end + return div, attr + end + / writer.div - local NoteBlock - = parsers.leader * RawNoteRef * parsers.colon - * parsers.spnl * parsers.indented_blocks(parsers.chunk) - / register_note + self.insert_pattern("Block after Verbatim", + FencedDiv, "FencedDiv") - local Blank = NoteBlock + parsers.Blank - self.update_rule("Blank", Blank) + self.add_special_character(":") +% \end{macrocode} +% \par +% \begin{markdown} +% +% If the `blank_before_div_fence` parameter is `false`, we will have the +% closing div at the beginning of a line break the current paragraph if +% we are currently nested in a div. +% +% \end{markdown} +% \begin{macrocode} + if not blank_before_div_fence then + local function check_div_level(s, i, current_level) -- luacheck: ignore s i + current_level = tonumber(current_level) + return current_level > 0 + end - self.insert_pattern("Inline after Emph", - NoteRef, "NoteRef") + local is_inside_div = Cmt(Cb("div_level"), check_div_level) + local fencestart = is_inside_div * fenced_div_end + self.update_rule("EndlineExceptions", function(previous_pattern) + if previous_pattern == nil then + previous_pattern = parsers.EndlineExceptions + end + return previous_pattern + fencestart + end) end - - self.add_special_character("^") end } end @@ -23307,8 +24104,8 @@ end % %#### Header Attributes % -% The \luamdef{extensions.header_attributes} function implements a syntax -% extension that enables the assignment of HTML attributes to headings. +% The \luamdef{extensions.header_attributes} function implements the Pandoc +% header attributes syntax extension. % % \end{markdown} % \begin{macrocode} @@ -23363,164 +24160,98 @@ M.extensions.header_attributes = function() / writer.heading local Heading = AtxHeading + SetextHeading - self.update_rule("Heading", Heading) + self.update_rule("Heading", function() return Heading end) end } end % \end{macrocode} % \begin{markdown} % -%#### YAML Metadata +%#### Notes % -% The \luamdef{extensions.jekyll_data} function implements the Pandoc -% `yaml_metadata_block` syntax extension for entering metadata in \acro{yaml}. -% When the `expect_jekyll_data` parameter is `true`, then a markdown document -% may begin directly with \acro{yaml} metadata and may contain nothing but -% \acro{yaml} metadata +% The \luamdef{extensions.notes} function implements the Pandoc note +% and inline note syntax extensions. When the `note` parameter is +% `true`, the Pandoc note syntax extension will be enabled. When the +% `inline_notes` parameter is `true`, the Pandoc inline note syntax +% extension will be enabled. % % \end{markdown} % \begin{macrocode} -M.extensions.jekyll_data = function(expect_jekyll_data) +M.extensions.notes = function(notes, inline_notes) + assert(notes or inline_notes) return { - name = "built-in jekyll_data syntax extension", + name = "built-in notes syntax extension", extend_writer = function(self) % \end{macrocode} % \par % \begin{markdown} % -% Define \luamdef{writer->jekyllData} as a function that will transform an -% input \acro{yaml} table `d` to the output format. The table is the value for -% the key `p` in the parent table; if `p` is nil, then the table has no parent. -% All scalar keys and values encountered in the table will be cast to a string -% following \acro{yaml} serialization rules. String values will also be -% transformed using the function `t`. +% Define \luamdef{writer->note} as a function that will transform an +% input note `s` to the output format. % % \end{markdown} % \begin{macrocode} - function self.jekyllData(d, t, p) - if not self.is_writing then return "" end + function self.note(s) + return {"\\markdownRendererNote{",s,"}"} + end + end, extend_reader = function(self) + local parsers = self.parsers + local writer = self.writer - local buf = {} + if inline_notes then + local InlineNote + = parsers.circumflex + * (parsers.tag / self.parser_functions.parse_inlines_no_inline_note) + / writer.note - local keys = {} - for k, _ in pairs(d) do - table.insert(keys, k) + self.insert_pattern("Inline after Emph", + InlineNote, "InlineNote") + end + if notes then + local function strip_first_char(s) + return s:sub(2) end - table.sort(keys) - if not p then - table.insert(buf, "\\markdownRendererJekyllDataBegin") - end + local RawNoteRef + = #(parsers.lbracket * parsers.circumflex) + * parsers.tag / strip_first_char - if #d > 0 then - table.insert(buf, "\\markdownRendererJekyllDataSequenceBegin{") - table.insert(buf, self.uri(p or "null")) - table.insert(buf, "}{") - table.insert(buf, #keys) - table.insert(buf, "}") - else - table.insert(buf, "\\markdownRendererJekyllDataMappingBegin{") - table.insert(buf, self.uri(p or "null")) - table.insert(buf, "}{") - table.insert(buf, #keys) - table.insert(buf, "}") - end + local rawnotes = {} - for _, k in ipairs(keys) do - local v = d[k] - local typ = type(v) - k = tostring(k or "null") - if typ == "table" and next(v) ~= nil then - table.insert( - buf, - self.jekyllData(v, t, k) - ) - else - k = self.uri(k) - v = tostring(v) - if typ == "boolean" then - table.insert(buf, "\\markdownRendererJekyllDataBoolean{") - table.insert(buf, k) - table.insert(buf, "}{") - table.insert(buf, v) - table.insert(buf, "}") - elseif typ == "number" then - table.insert(buf, "\\markdownRendererJekyllDataNumber{") - table.insert(buf, k) - table.insert(buf, "}{") - table.insert(buf, v) - table.insert(buf, "}") - elseif typ == "string" then - table.insert(buf, "\\markdownRendererJekyllDataString{") - table.insert(buf, k) - table.insert(buf, "}{") - table.insert(buf, t(v)) - table.insert(buf, "}") - elseif typ == "table" then - table.insert(buf, "\\markdownRendererJekyllDataEmpty{") - table.insert(buf, k) - table.insert(buf, "}") + -- like indirect_link + local function lookup_note(ref) + return writer.defer_call(function() + local found = rawnotes[self.normalize_tag(ref)] + if found then + return writer.note( + self.parser_functions.parse_blocks_nested(found)) else - error(format("Unexpected type %s for value of " .. - "YAML key %s", typ, k)) + return {"[", + self.parser_functions.parse_inlines("^" .. ref), "]"} end - end - end - - if #d > 0 then - table.insert(buf, "\\markdownRendererJekyllDataSequenceEnd") - else - table.insert(buf, "\\markdownRendererJekyllDataMappingEnd") + end) end - if not p then - table.insert(buf, "\\markdownRendererJekyllDataEnd") + local function register_note(ref,rawnote) + rawnotes[self.normalize_tag(ref)] = rawnote + return "" end - return buf - end - end, extend_reader = function(self) - local parsers = self.parsers - local writer = self.writer - - local JekyllData - = Cmt( C((parsers.line - P("---") - P("..."))^0) - , function(s, i, text) -- luacheck: ignore s i - local data - local ran_ok, _ = pcall(function() - local tinyyaml = require("markdown-tinyyaml") - data = tinyyaml.parse(text, {timestamps=false}) - end) - if ran_ok and data ~= nil then - return true, writer.jekyllData(data, function(s) - return self.parser_functions.parse_blocks_nested(s) - end, nil) - else - return false - end - end - ) + local NoteRef = RawNoteRef / lookup_note - local UnexpectedJekyllData - = P("---") - * parsers.blankline / 0 - * #(-parsers.blankline) -- if followed by blank, it's thematic break - * JekyllData - * (P("---") + P("...")) + local NoteBlock + = parsers.leader * RawNoteRef * parsers.colon + * parsers.spnl * parsers.indented_blocks(parsers.chunk) + / register_note - local ExpectedJekyllData - = ( P("---") - * parsers.blankline / 0 - * #(-parsers.blankline) -- if followed by blank, it's thematic break - )^-1 - * JekyllData - * (P("---") + P("..."))^-1 + local Blank = NoteBlock + parsers.Blank + self.update_rule("Blank", function() return Blank end) - self.insert_pattern("Block before Blockquote", - UnexpectedJekyllData, "UnexpectedJekyllData") - if expect_jekyll_data then - self.update_rule("ExpectedJekyllData", ExpectedJekyllData) + self.insert_pattern("Inline after Emph", + NoteRef, "NoteRef") end + + self.add_special_character("^") end } end @@ -23530,7 +24261,7 @@ end %#### Pipe Tables % % The \luamdef{extensions.pipe_table} function implements the \acro{PHP} -% Markdown table syntax extension (affectionately known as pipe tables). When +% Markdown table syntax extension (also known as pipe tables in Pandoc). When % the `table_captions` parameter is `true`, the function also implements the % Pandoc `table_captions` syntax extension for table captions. % @@ -23708,7 +24439,7 @@ M.extensions.raw_attribute = function() % \begin{markdown} % % Define \luamdef{writer->rawInline} as a function that will transform an -% input inline raw span `s` with the raw attribute `i` to the output format. +% input inline raw span `s` with the raw attribute `attr` to the output format. % % \end{markdown} % \begin{macrocode} @@ -23725,7 +24456,7 @@ M.extensions.raw_attribute = function() % \begin{markdown} % % Define \luamdef{writer->rawBlock} as a function that will transform an -% input raw block `s` with the raw attribute `i` to the output format. +% input raw block `s` with the raw attribute `attr` to the output format. % % \end{markdown} % \begin{macrocode} @@ -23756,17 +24487,17 @@ M.extensions.raw_attribute = function() if options.fencedCode then local RawBlock = (parsers.TildeFencedCode - + parsers.BacktickFencedCode) - / function(infostring, code) - local expanded_code = self.expandtabs(code) - local attr = lpeg.match(raw_attribute, infostring) - if attr then - return writer.rawBlock(expanded_code, attr) - else - return writer.fencedCode(expanded_code, - infostring) - end + + parsers.BacktickFencedCode) + / function(infostring, code) + local expanded_code = self.expandtabs(code) + local attr = lpeg.match(raw_attribute, infostring) + if attr then + return writer.rawBlock(expanded_code, attr) + else + return writer.fencedCode(expanded_code, + infostring) end + end self.insert_pattern("Block after Verbatim", RawBlock, "RawBlock") @@ -23819,283 +24550,238 @@ end % \end{macrocode} % \begin{markdown} % -%#### Superscripts +%#### Subscripts % -% The \luamdef{extensions.superscripts} function implements the Pandoc -% superscript syntax extension. +% The \luamdef{extensions.subscripts} function implements the Pandoc +% subscript syntax extension. % % \end{markdown} % \begin{macrocode} -M.extensions.superscripts = function() +M.extensions.subscripts = function() return { - name = "built-in superscripts syntax extension", + name = "built-in subscripts syntax extension", extend_writer = function(self) % \end{macrocode} % \par % \begin{markdown} % -% Define \luamdef{writer->superscript} as a function that will transform -% a superscript span `s` of input text to the output format. +% Define \luamdef{writer->subscript} as a function that will transform +% a subscript span `s` of input text to the output format. % % \end{markdown} % \begin{macrocode} - function self.superscript(s) - return {"\\markdownRendererSuperscript{",s,"}"} + function self.subscript(s) + return {"\\markdownRendererSubscript{",s,"}"} end end, extend_reader = function(self) local parsers = self.parsers local writer = self.writer - local Superscript = ( - parsers.between(parsers.Str, parsers.circumflex, parsers.circumflex) - ) / writer.superscript + local Subscript = ( + parsers.between(parsers.Str, parsers.tilde, parsers.tilde) + ) / writer.subscript self.insert_pattern("Inline after Emph", - Superscript, "Superscript") + Subscript, "Subscript") - self.add_special_character("^") + self.add_special_character("~") end } end % \end{macrocode} % \begin{markdown} % -%#### Subscripts +%#### Superscripts % -% The \luamdef{extensions.subscripts} function implements the Pandoc -% subscript syntax extension. +% The \luamdef{extensions.superscripts} function implements the Pandoc +% superscript syntax extension. % % \end{markdown} % \begin{macrocode} -M.extensions.subscripts = function() +M.extensions.superscripts = function() return { - name = "built-in subscripts syntax extension", + name = "built-in superscripts syntax extension", extend_writer = function(self) % \end{macrocode} % \par % \begin{markdown} % -% Define \luamdef{writer->subscript} as a function that will transform -% a subscript span `s` of input text to the output format. +% Define \luamdef{writer->superscript} as a function that will transform +% a superscript span `s` of input text to the output format. % % \end{markdown} % \begin{macrocode} - function self.subscript(s) - return {"\\markdownRendererSubscript{",s,"}"} + function self.superscript(s) + return {"\\markdownRendererSuperscript{",s,"}"} end end, extend_reader = function(self) local parsers = self.parsers local writer = self.writer - local Subscript = ( - parsers.between(parsers.Str, parsers.tilde, parsers.tilde) - ) / writer.subscript + local Superscript = ( + parsers.between(parsers.Str, parsers.circumflex, parsers.circumflex) + ) / writer.superscript self.insert_pattern("Inline after Emph", - Subscript, "Subscript") + Superscript, "Superscript") - self.add_special_character("~") + self.add_special_character("^") end } end % \end{macrocode} % \begin{markdown} % -%#### Fancy Lists +%#### YAML Metadata % -% The \luamdef{extensions.fancy_lists} function implements the Pandoc fancy -% list extension. +% The \luamdef{extensions.jekyll_data} function implements the Pandoc +% `yaml_metadata_block` syntax extension. When the `expect_jekyll_data` +% parameter is `true`, then a markdown document may begin directly with +% \acro{yaml} metadata and may contain nothing but \acro{yaml} metadata. % % \end{markdown} % \begin{macrocode} -M.extensions.fancy_lists = function() +M.extensions.jekyll_data = function(expect_jekyll_data) return { - name = "built-in fancy_lists syntax extension", + name = "built-in jekyll_data syntax extension", extend_writer = function(self) - local options = self.options - % \end{macrocode} % \par % \begin{markdown} % -% Define \luamdef{writer->fancylist} as a function that will transform an -% input ordered list to the output format, where: -% -%- `items` is an array of the list items, -%- `tight` specifies, whether the list is tight or not, -%- `startnum` is the number of the first list item, -%- `numstyle` is the style of the list item labels from among the following: -% - `Decimal` -- decimal arabic numbers, -% - `LowerRoman` -- lower roman numbers, -% - `UpperRoman` -- upper roman numbers, -% - `LowerAlpha` -- lower ASCII alphabetic characters, and -% - `UpperAlpha` -- upper ASCII alphabetic characters, and -%- `numdelim` is the style of delimiters between list item labels and -% texts from among the following: -% - `Default` -- default style, -% - `OneParen` -- parentheses, and -% - `Period` -- periods. +% Define \luamdef{writer->jekyllData} as a function that will transform an +% input \acro{yaml} table `d` to the output format. The table is the value for +% the key `p` in the parent table; if `p` is nil, then the table has no parent. +% All scalar keys and values encountered in the table will be cast to a string +% following \acro{yaml} serialization rules. String values will also be +% transformed using the function `t`. % % \end{markdown} % \begin{macrocode} - function self.fancylist(items,tight,startnum,numstyle,numdelim) + function self.jekyllData(d, t, p) if not self.is_writing then return "" end - local buffer = {} - local num = startnum - for _,item in ipairs(items) do - buffer[#buffer + 1] = self.fancyitem(item,num) - if num ~= nil then - num = num + 1 - end - end - local contents = util.intersperse(buffer,"\n") - if tight and options.tightLists then - return {"\\markdownRendererFancyOlBeginTight{", - numstyle,"}{",numdelim,"}",contents, - "\n\\markdownRendererFancyOlEndTight "} - else - return {"\\markdownRendererFancyOlBegin{", - numstyle,"}{",numdelim,"}",contents, - "\n\\markdownRendererFancyOlEnd "} - end - end -% \end{macrocode} -% \begin{markdown} -% -% Define \luamdef{writer->fancyitem} as a function that will transform an -% input fancy ordered list item to the output format, where `s` is the text of -% the list item. If the optional parameter `num` is present, it is the number -% of the list item. -% -% \end{markdown} -% \begin{macrocode} - function self.fancyitem(s,num) - if num ~= nil then - return {"\\markdownRendererFancyOlItemWithNumber{",num,"}",s, - "\\markdownRendererFancyOlItemEnd "} - else - return {"\\markdownRendererFancyOlItem ",s,"\\markdownRendererFancyOlItemEnd "} - end - end - end, extend_reader = function(self) - local parsers = self.parsers - local options = self.options - local writer = self.writer - - local label = parsers.dig + parsers.letter - local numdelim = parsers.period + parsers.rparent - local enumerator = C(label^3 * numdelim) * #parsers.spacing - + C(label^2 * numdelim) * #parsers.spacing - * (parsers.tab + parsers.space^1) - + C(label * numdelim) * #parsers.spacing - * (parsers.tab + parsers.space^-2) - + parsers.space * C(label^2 * numdelim) - * #parsers.spacing - + parsers.space * C(label * numdelim) - * #parsers.spacing - * (parsers.tab + parsers.space^-1) - + parsers.space * parsers.space * C(label^1 - * numdelim) * #parsers.spacing - local starter = parsers.bullet + enumerator - - local NestedList = Cs((parsers.optionallyindentedline - - starter)^1) - / function(a) return "\001"..a end - - local ListBlockLine = parsers.optionallyindentedline - - parsers.blankline - (parsers.indent^-1 - * starter) - - local ListBlock = parsers.line * ListBlockLine^0 - local ListContinuationBlock = parsers.blanklines * (parsers.indent / "") - * ListBlock + local buf = {} - local TightListItem = function(starter) - return -parsers.ThematicBreak - * (Cs(starter / "" * parsers.tickbox^-1 * ListBlock * NestedList^-1) - / self.parser_functions.parse_blocks_nested) - * -(parsers.blanklines * parsers.indent) - end + local keys = {} + for k, _ in pairs(d) do + table.insert(keys, k) + end + table.sort(keys) - local LooseListItem = function(starter) - return -parsers.ThematicBreak - * Cs( starter / "" * parsers.tickbox^-1 * ListBlock * Cc("\n") - * (NestedList + ListContinuationBlock^0) - * (parsers.blanklines / "\n\n") - ) / self.parser_functions.parse_blocks_nested - end + if not p then + table.insert(buf, "\\markdownRendererJekyllDataBegin") + end - local function roman2number(roman) - local romans = { ["L"] = 50, ["X"] = 10, ["V"] = 5, ["I"] = 1 } - local numeral = 0 + if #d > 0 then + table.insert(buf, "\\markdownRendererJekyllDataSequenceBegin{") + table.insert(buf, self.uri(p or "null")) + table.insert(buf, "}{") + table.insert(buf, #keys) + table.insert(buf, "}") + else + table.insert(buf, "\\markdownRendererJekyllDataMappingBegin{") + table.insert(buf, self.uri(p or "null")) + table.insert(buf, "}{") + table.insert(buf, #keys) + table.insert(buf, "}") + end - local i = 1 - local len = string.len(roman) - while i < len do - local z1, z2 = romans[ string.sub(roman, i, i) ], romans[ string.sub(roman, i+1, i+1) ] - if z1 < z2 then - numeral = numeral + (z2 - z1) - i = i + 2 + for _, k in ipairs(keys) do + local v = d[k] + local typ = type(v) + k = tostring(k or "null") + if typ == "table" and next(v) ~= nil then + table.insert( + buf, + self.jekyllData(v, t, k) + ) else - numeral = numeral + z1 - i = i + 1 + k = self.uri(k) + v = tostring(v) + if typ == "boolean" then + table.insert(buf, "\\markdownRendererJekyllDataBoolean{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, v) + table.insert(buf, "}") + elseif typ == "number" then + table.insert(buf, "\\markdownRendererJekyllDataNumber{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, v) + table.insert(buf, "}") + elseif typ == "string" then + table.insert(buf, "\\markdownRendererJekyllDataString{") + table.insert(buf, k) + table.insert(buf, "}{") + table.insert(buf, t(v)) + table.insert(buf, "}") + elseif typ == "table" then + table.insert(buf, "\\markdownRendererJekyllDataEmpty{") + table.insert(buf, k) + table.insert(buf, "}") + else + error(format("Unexpected type %s for value of " .. + "YAML key %s", typ, k)) + end end end - if i <= len then numeral = numeral + romans[ string.sub(roman,i,i) ] end - return numeral - end - local function sniffstyle(itemprefix) - local numstr, delimend = itemprefix:match("^([A-Za-z0-9]*)([.)]*)") - local numdelim - if delimend == ")" then - numdelim = "OneParen" - elseif delimend == "." then - numdelim = "Period" + if #d > 0 then + table.insert(buf, "\\markdownRendererJekyllDataSequenceEnd") else - numdelim = "Default" + table.insert(buf, "\\markdownRendererJekyllDataMappingEnd") end - numstr = numstr or itemprefix - local num - num = numstr:match("^([IVXL]+)") - if num then - return roman2number(num), "UpperRoman", numdelim - end - num = numstr:match("^([ivxl]+)") - if num then - return roman2number(string.upper(num)), "LowerRoman", numdelim - end - num = numstr:match("^([A-Z])") - if num then - return string.byte(num) - string.byte("A") + 1, "UpperAlpha", numdelim - end - num = numstr:match("^([a-z])") - if num then - return string.byte(num) - string.byte("a") + 1, "LowerAlpha", numdelim + if not p then + table.insert(buf, "\\markdownRendererJekyllDataEnd") end - return math.floor(tonumber(numstr) or 1), "Decimal", numdelim - end - local function fancylist(items,tight,start) - local startnum, numstyle, numdelim = sniffstyle(start) - return writer.fancylist(items,tight, - options.startNumber and startnum, - numstyle or "Decimal", - numdelim or "Default") + return buf end + end, extend_reader = function(self) + local parsers = self.parsers + local writer = self.writer - local FancyList = Cg(enumerator, "listtype") * - ( Ct(TightListItem(Cb("listtype")) - * TightListItem(enumerator)^0) - * Cc(true) * parsers.skipblanklines * -enumerator - + Ct(LooseListItem(Cb("listtype")) - * LooseListItem(enumerator)^0) - * Cc(false) * parsers.skipblanklines - ) * Cb("listtype") / fancylist + local JekyllData + = Cmt( C((parsers.line - P("---") - P("..."))^0) + , function(s, i, text) -- luacheck: ignore s i + local data + local ran_ok, _ = pcall(function() + local tinyyaml = require("markdown-tinyyaml") + data = tinyyaml.parse(text, {timestamps=false}) + end) + if ran_ok and data ~= nil then + return true, writer.jekyllData(data, function(s) + return self.parser_functions.parse_blocks_nested(s) + end, nil) + else + return false + end + end + ) + + local UnexpectedJekyllData + = P("---") + * parsers.blankline / 0 + * #(-parsers.blankline) -- if followed by blank, it's thematic break + * JekyllData + * (P("---") + P("...")) + + local ExpectedJekyllData + = ( P("---") + * parsers.blankline / 0 + * #(-parsers.blankline) -- if followed by blank, it's thematic break + )^-1 + * JekyllData + * (P("---") + P("..."))^-1 - self.update_rule("OrderedList", FancyList) + self.insert_pattern("Block before Blockquote", + UnexpectedJekyllData, "UnexpectedJekyllData") + if expect_jekyll_data then + self.update_rule("ExpectedJekyllData", function() return ExpectedJekyllData end) + end end } end @@ -24132,6 +24818,11 @@ function M.new(options) % \begin{macrocode} local extensions = {} + if options.bracketedSpans then + local bracketed_spans_extension = M.extensions.bracketed_spans() + table.insert(extensions, bracketed_spans_extension) + end + if options.contentBlocks then local content_blocks_extension = M.extensions.content_blocks( options.contentBlocksLanguageMap) @@ -24150,6 +24841,12 @@ function M.new(options) table.insert(extensions, fenced_code_extension) end + if options.fencedDivs then + local fenced_div_extension = M.extensions.fenced_divs( + options.blankBeforeDivFence) + table.insert(extensions, fenced_div_extension) + end + if options.headerAttributes then local header_attributes_extension = M.extensions.header_attributes() table.insert(extensions, header_attributes_extension) @@ -24870,14 +25567,14 @@ end % % The \mdef{markdownPrepare} macro contains the Lua code that is executed prior % to any conversion from markdown to plain \TeX{}. It exposes the -% \luamref{convert} function for the use by any further Lua code. +% `convert` function for the use by any further Lua code. % % \end{markdown} % \begin{macrocode} \def\markdownPrepare{% % \end{macrocode} % \begin{markdown} -% First, ensure that the \mref{markdownOptionCacheDir} directory exists. +% First, ensure that the \Opt{cacheDir} directory exists. % \end{markdown} % \begin{macrocode} local lfs = require("lfs") @@ -24973,7 +25670,7 @@ end % \begin{markdown} % % The \mref{markdownReadAndConvert} macro is largely a rewrite of the -% \Hologo{LaTeX2e} \mref{filecontents} macro to plain \TeX{}. +% \Hologo{LaTeX2e} `\filecontents` macro to plain \TeX{}. % % \end{markdown} % \begin{macrocode} @@ -24985,7 +25682,7 @@ end % backslash as an ordinary character inside the macro definition. Likewise, % swap the character codes of the percent sign (`\%`) and the ampersand (`@`), % so that we can remove percent signs from the beginning of lines when -% \mref{markdownOptionStripPercentSigns} is enabled. +% \Opt{stripPercentSigns} is enabled. % \end{markdown} % \begin{macrocode} \catcode`\^^M=13% @@ -24999,7 +25696,7 @@ end % \end{macrocode} % \begin{markdown} % If we are not reading markdown documents from the frozen cache, -% open the \mref{markdownOptionInputTempFileName} file for writing. +% open the \Opt{inputTempFileName} file for writing. % \end{markdown} % \begin{macrocode} |markdownIfOption{frozenCache}{}{@ @@ -25024,7 +25721,7 @@ end % \begin{markdown} % The \mdef{markdownReadAndConvertStripPercentSigns} macro will process the % individual lines of output, stipping away leading percent signs (`\%`) when -% \mref{markdownOptionStripPercentSigns} is enabled. +% \Opt{stripPercentSigns} is enabled. % Notice the use of the comments (`@`) to ensure that the entire macro is at % a single line and therefore no (active) newline symbols % (`^^M`) are produced. @@ -25060,7 +25757,7 @@ end % \begin{markdown} % If we are not reading markdown documents from the frozen cache and the ending % token sequence does not appear in the line, store the line in the -% \mref{markdownOptionInputTempFileName} file. +% \Opt{inputTempFileName} file. % If we are reading markdown documents from the frozen cache and the % ending token sequence does not appear in the line, gobble the line. % \end{markdown} @@ -25073,10 +25770,10 @@ end % \end{macrocode} % \begin{markdown} % When the ending token sequence appears in the line, make the next newline -% character close the \mref{markdownOptionInputTempFileName} file, return the +% character close the \Opt{inputTempFileName} file, return the % character categories back to the former state, convert the -% \mref{markdownOptionInputTempFileName} file from markdown to plain \TeX{}, -% \mref{input} the result of the conversion, and expand the ending control +% \Opt{inputTempFileName} file from markdown to plain \TeX{}, +% `\input` the result of the conversion, and expand the ending control % sequence. % \end{markdown} % \begin{macrocode} @@ -25181,10 +25878,10 @@ end % whether the shell access is enabled (`1`), disabled (`0`), or restricted % (`2`). % -% Inherit the value of the the \mref{pdfshellescape} (Lua\TeX{}, \Hologo{pdfTeX}) -% or the \mref{shellescape} (\Hologo{XeTeX}) commands. If neither of these +% Inherit the value of the the `\pdfshellescape` (Lua\TeX{}, \Hologo{pdfTeX}) +% or the `\shellescape` (\Hologo{XeTeX}) commands. If neither of these % commands is defined and Lua is available, attempt to access the -% \luamref{status.shell_escape} configuration item. +% `status.shell_escape` configuration item. % % If you cannot detect, whether the shell access is enabled, act as if it were. % @@ -25210,7 +25907,7 @@ end % % The \mdef{markdownExecuteDirect} macro executes the code it has received as % its first argument by writing it to the output file stream 18, if Lua is -% unavailable, or by using the Lua \luamref{os.execute} method otherwise. +% unavailable, or by using the Lua `os.execute` method otherwise. % % \end{markdown} % \begin{macrocode} @@ -25245,8 +25942,8 @@ end % % The \mdef{markdownLuaExecute} macro executes the Lua code it has received as % its first argument. The Lua code may not directly interact with the \TeX{} -% engine, but it can use the \luamref{print} function in the same manner it -% would use the \luamref{tex.print} method. +% engine, but it can use the `print` function in the same manner it +% would use the `tex.print` method. % % \end{markdown} % \begin{macrocode} @@ -25262,7 +25959,7 @@ end |gdef|markdownLuaExecute#1{% % \end{macrocode} % \begin{markdown} -% Create the file \mref{markdownOptionHelperScriptFileName} and fill it with the +% Create the file \Opt{helperScriptFileName} and fill it with the % input Lua code prepended with \pkg{kpathsea} initialization, so that Lua % modules from the \TeX{} distribution are available. % \end{markdown} @@ -25279,7 +25976,7 @@ end end) % \end{macrocode} % \begin{markdown} -% If there was an error, use the file \mref{markdownOptionErrorTempFileName} to +% If there was an error, use the file \Opt{errorTempFileName} to % store the error message. % \end{markdown} % \begin{macrocode} @@ -25299,9 +25996,9 @@ end |immediate|closeout|markdownOutputFileStream % \end{macrocode} % \begin{markdown} -% Execute the generated \mref{markdownOptionHelperScriptFileName} Lua script using +% Execute the generated \Opt{helperScriptFileName} Lua script using % the \TeX{}Lua binary and store the output in the -% \mref{markdownOptionOutputTempFileName} file. +% \Opt{outputTempFileName} file. % \end{markdown} % \begin{macrocode} |markdownInfo{Executing a helper Lua script from the file @@ -25313,7 +26010,7 @@ end /|markdownOptionOutputTempFileName"}% % \end{macrocode} % \begin{markdown} -% \mref{input} the generated \mref{markdownOptionOutputTempFileName} file. +% `\input` the generated \Opt{outputTempFileName} file. % \end{markdown} % \begin{macrocode} |input|markdownOptionOutputTempFileName|relax}% @@ -25340,8 +26037,8 @@ end % \begin{markdown} % % The direct Lua access version of the \mref{markdownLuaExecute} macro is defined -% in terms of the \mref{directlua} primitive. The \luamref{print} function is set as -% an alias to the \luamref{tex.print} method in order to mimic the behaviour of the +% in terms of the `\directlua` primitive. The `print` function is set as +% an alias to the `tex.print` method in order to mimic the behaviour of the % \mref{markdownLuaExecute} definition from Section <#sec:luabridge>, % % \end{markdown} @@ -25520,8 +26217,8 @@ end % %### Logging Facilities % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section <#sec:texinterfacelogging>) to use the \LaTeX{} \mref{PackageInfo}, -% \mref{PackageWarning}, and \mref{PackageError} macros. +% Section <#sec:texinterfacelogging>) to use the \LaTeX{} `\PackageInfo`, +% `\PackageWarning`, and `\PackageError` macros. % % \end{markdown} % \begin{macrocode} @@ -25660,7 +26357,7 @@ end % % If the infostring starts with `dot …`, we redefine the fenced code block % token renderer prototype, so that it typesets the code block via Graphviz -% tools if and only if the \mref{markdownOptionFrozenCache} plain \TeX{} option is +% tools if and only if the \Opt{frozenCache} plain \TeX{} option is % disabled and the code block has not been previously typeset: % % \end{markdown} @@ -25723,8 +26420,8 @@ end % \end{macrocode} % \begin{markdown} % -% We define the \mref{markdown@witiko@graphicx@http@counter} counter to enumerate -% the images for caching and the \mref{markdown@witiko@graphicx@http@filename} +% We define the \mdef{markdown@witiko@graphicx@http@counter} counter to enumerate +% the images for caching and the \mdef{markdown@witiko@graphicx@http@filename} % command, which will store the pathname of the file containing the pathname % of the downloaded image file. % @@ -25738,7 +26435,7 @@ end % \end{macrocode} % \begin{markdown} % -% We define the \mref{markdown@witiko@graphicx@http@download} command, which will +% We define the \mdef{markdown@witiko@graphicx@http@download} command, which will % receive two arguments that correspond to the URL of the online image and to % the pathname, where the online image should be downloaded. The command will % produce a shell command that tries to downloads the online image to the @@ -25774,7 +26471,7 @@ end % \begin{markdown} % % The image will be downloaded only if the image URL has the http or https -% protocols and the \mref{markdownOptionFrozenCache} plain \TeX{} option is disabled: +% protocols and the \Opt{frozenCache} plain \TeX{} option is disabled: % % \end{markdown} % \begin{macrocode} @@ -25786,7 +26483,7 @@ end % \end{macrocode} % \begin{markdown} % -% The image will be downloaded to the pathname \mref{markdownOptionCacheDir}<!-- +% The image will be downloaded to the pathname \Opt{cacheDir}<!-- % -->`/`\meta{the MD5 digest of the image URL}`.`\meta{the suffix of the % image URL}: % @@ -26255,7 +26952,7 @@ end % \begin{markdown} % % If identifier attributes appear at the beginning of a section, we make the -% next heading produce the \mref{label} macro. +% next heading produce the `\label` macro. % % \end{markdown} % \begin{macrocode} @@ -26439,9 +27136,9 @@ end % \begin{markdown} % %#### Citations -% Here is a basic implementation for citations that uses the \LaTeX{} \mref{cite} -% macro. There are also implementations that use the \pkg{natbib} \mref{citep}, -% and \mref{citet} macros, and the Bib\LaTeX{} \mref{autocites} and \mref{textcites} +% Here is a basic implementation for citations that uses the \LaTeX{} `\cite` +% macro. There are also implementations that use the \pkg{natbib} `\citep`, +% and `\citet` macros, and the Bib\LaTeX{} `\autocites` and `\textcites` % macros. These implementations will be used, when the respective packages are % loaded. % @@ -26849,8 +27546,8 @@ end % %#### YAML Metadata {#latexyamlmetadata} % -% The default setup of \acro{yaml} metadata will invoke the \mref{title}, -% \mref{author}, and \mref{date} macros when scalar values for keys that +% The default setup of \acro{yaml} metadata will invoke the `\title`, +% `\author`, and `\date` macros when scalar values for keys that % correspond to the `title`, `author`, and `date` relative wildcards are % encountered, respectively. % @@ -26868,10 +27565,10 @@ end % \begin{markdown} % % To complement the default setup of our key--values, we will use -% the \mref{maketitle} macro to typeset the title page of a document +% the `\maketitle` macro to typeset the title page of a document % at the end of \acro{yaml} metadata. If we are in the preamble, we will wait % macro until after the beginning of the document. Otherwise, we will use -% the \mref{maketitle} macro straight away. +% the `\maketitle` macro straight away. % % \end{markdown} % \begin{macrocode} @@ -26984,7 +27681,7 @@ end % after supplying the missing plain \TeX{} macros. % % When buffering user input, we should disable the bytes with the high bit set, -% since these are made active by the \mref{enableregime} macro. We will do this +% since these are made active by the `\enableregime` macro. We will do this % by redefining the \mref{markdownMakeOther} macro accordingly. The code is % courtesy of Scott Pakin, the creator of the \pkg{filecontents} \LaTeX{} % package. @@ -27169,7 +27866,7 @@ end % \begin{markdown} % % The code fence infostring is used as a name from the \Hologo{ConTeXt} -% \mref{definetyping} macro. This allows the user to set up code highlighting +% `\definetyping` macro. This allows the user to set up code highlighting % mapping as follows: % ````` tex % % Map the `TEX` syntax highlighter to the `latex` infostring. |