diff options
Diffstat (limited to 'Master/texmf-dist/source')
-rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 441 |
1 files changed, 393 insertions, 48 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx index fad63a37918..b624b048799 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.dtx +++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx @@ -4,8 +4,11 @@ \documentclass{ltxdockit} \usepackage[american]{babel} \usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted,varioref} +\vrefwarning % Set up the style. +\usepackage{xcolor} +\definecolor{spot}{rgb}{0,0.2,0.6} \usepackage{fontspec} \defaultfontfeatures[\rmfamily,\sffamily,\ttfamily]{} \emergencystretch=1em @@ -83,10 +86,10 @@ html, jekyllData, stripPercentSigns, - underscores=false, - theme=witiko/dot, - theme=witiko/graphicx/http, - theme=witiko/markdown/techdoc, + underscores = false, + theme = witiko/dot, + theme = witiko/graphicx/http, + theme = witiko/markdown/techdoc, ]{markdown} % Set up Unicode characters. @@ -720,13 +723,26 @@ abbr { pagetotal = {xviii, 347}, location = {Rio de Janeiro}, publisher = {PUC-Rio}} -@book{knuth86, +@book{knuth86a, author = {Knuth, Donald Ervin}, year = {1986}, title = {The \TeX{}book}, edition = {3}, isbn = {0-201-13447-0}, pagetotal = {ix, 479}, + series = {Computers \& Typesetting}, + volume = {A}, + location = {Reading, MA}, + publisher = {Addison-Wesley}} +@book{knuth86b, + author = {Knuth, Donald Ervin}, + year = {1986}, + title = {\TeX: The Program}, + isbn = {0-201-13437-7}, + pagetotal = {xvi, 594}, + series = {Computers \& Typesetting}, + volume = {B}, + location = {Reading, MA}, publisher = {Addison-Wesley}} @online{novotny21, author = {Novotný, Vít}, @@ -734,6 +750,15 @@ abbr { date = {2021-02-20}, url = {https://github.com/latex3/latex2e/issues/510}, urldate = {2021-02-21}} +@book{eijkhout92, + author = {Victor Eijkhout}, + title = {\TeX{} by Topic}, + subtitle = {A \TeX nician's Reference}, + isbn = {0-201-56882-0}, + pagetotal = {307}, + date = {1992-02-01}, + location = {Wokingham, England}, + publisher = {Addison-Wesley}} %</techdoc-bibliography> %<*latex-themes-witiko-markdown-techdoc> \ProvidesPackage{markdownthemewitiko_markdown_techdoc}[2021/09/10] @@ -3838,6 +3863,97 @@ defaultOptions.definitionLists = false %</lua,lua-cli> %<*manual-options> +#### Option `eagerCache` + +`eagerCache` (default value: `true`) + +% \fi +% \begin{markdown} +% +% \Optitem[true]{eagerCache}{\opt{true}, \opt{false}} +% +: true + + Converted markdown documents will be cached in \Opt{cacheDir}. This can be + useful for post-processing the converted documents and for recovering + historical versions of the documents from the cache. However, it also + produces a large number of auxiliary files on the disk and obscures the + output of the Lua command-line interface when it is used for plumbing. + + This behavior will always be used if the \Opt{finalizeCache} option is + enabled. + +: false + + Converted markdown documents will not be cached. This decreases the number + of auxiliary files that we produce and makes it easier to use the Lua + command-line interface for plumbing. + + This behavior will only be used when the \Opt{finalizeCache} option is + disabled. Furthermore, this behavior is planned to be the new default in + the next major release of the Markdown package. + +% \end{markdown} +% \iffalse + +##### Lua Module Example {.unnumbered} + +Using a text editor, create a text document named `hello.md` with the +following content: +``` md +Hello *world*! +`````` +Next, invoke LuaTeX from the terminal with the \Opt{eagerCache} option +disabled: +``` sh +texlua ⟨CLI pathname⟩ eagerCache=false -- hello.md hello.tex +``````` +where \meta{CLI pathname} corresponds to the location of the Lua CLI script file, +such as `~/texmf/scripts/markdown/markdown-cli.lua` on UN\*X systems or +`C:\Users\`\meta{Your username}`\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich -a markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A \TeX{} document named `hello.tex` should be produced and contain the +following code: +``` tex +Hello \markdownRendererEmphasis{world}!\relax +``` + +*** + +Invoke LuaTeX from the terminal again, this time with the \Opt{eagerCache} +option enabled: + +``` tex +texlua ⟨CLI pathname⟩ eagerCache=true -- hello.md hello.tex +``` + +A \TeX{} document named `hello.tex` should be produced and contain the +following code: + +``` tex +\input ./⟨hash⟩.md.tex\relax +``` + +Additionally, a \TeX{} document named `⟨hash⟩.md.tex` should be produced and +contain the following code: + +``` tex +Hello \markdownRendererEmphasis{world}!\relax +``` + +%</manual-options> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.eagerCache = true +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `fencedCode` `fencedCode` (default value: `false`) @@ -4364,6 +4480,80 @@ defaultOptions.frozenCacheCounter = 0 %</lua,lua-cli> %<*manual-options> +#### Option `hardLineBreaks` + +`hardLineBreaks` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{hardLineBreaks}{\opt{true}, \opt{false}} +% +: true + + : Interpret all newlines within a paragraph as hard line breaks instead + of spaces. + +: false + + : Interpret all newlines within a paragraph as spaces. + +% \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} +\begin{document} + +\begin{markdown} +'Twas brillig, and the slithy toves +Did gyre and gimble in the wabe; +All mimsy were the borogoves, +And the mome raths outgrabe. +\end{markdown} + +\begin{markdown*}{hardLineBreaks} +'Twas brillig, and the slithy toves +Did gyre and gimble in the wabe; +All mimsy were the borogoves, +And the mome raths outgrabe. +\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: + +> 'Twas brillig, and the slithy toves +> Did gyre and gimble in the wabe; +> All mimsy were the borogoves, +> And the mome raths outgrabe. +> +> 'Twas brillig, and the slithy toves +> Did gyre and gimble in the wabe; +> All mimsy were the borogoves, +> And the mome raths outgrabe. + +%</manual-options> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.hardLineBreaks = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `hashEnumerators` `hashEnumerators` (default value: `false`) @@ -6983,7 +7173,7 @@ pdftex --shell-escape document.tex % Another limitation concerns spaces at the right end of an input line. In % markdown, these are used to produce a forced line break. However, any such % spaces are removed before the lines enter the input buffer of -% \TeX{}~[@knuth86, p. 46]. As a corrolary, the \mref{markdownBegin} macro also +% \TeX{}~[@knuth86a, p. 46]. As a corrolary, the \mref{markdownBegin} macro also % ignores them. % % The \mref{markdownBegin} and \mref{markdownEnd} macros will also consume the rest @@ -7057,6 +7247,16 @@ the `markdown` Lua module. They are supported by all higher-level interfaces of the Markdown package, i.e. the plain \TeX{}, \LaTeX{} and \Hologo{ConTeXt} interfaces. +#### Setting Lua options from plain \TeX{} + +As a rule of thumb, you can set all Lua options directly from plain \TeX{}. For +example, to set the \Opt{taskLists} Lua option to `true`, you would include the +following code in your plain \TeX{} document: + +``` tex +\def\markdownOptionTaskLists{true} +``` + %</manual-options> %<*tex> % \fi @@ -7096,7 +7296,7 @@ defaults to `false`. % The standard usage of the above two options is as follows: % \iffalse -The standard usage of the \Opt{finalizeCache} and \mref{markdownOptionFrozenCache} +The standard usage of the \Opt{finalizeCache} and \Opt{frozenCache} options is as follows: % \fi @@ -7241,6 +7441,9 @@ Markdown to \TeX{}: - `\markdownOptionCacheDir`, and - `\markdownOptionFrozenCacheFileName`. +The `\markdownOptionCacheDir` and `\markdownOptionFrozenCacheFileName` commands +correspond to the `cacheDir` and `frozenCacheFileName` Lua options. + Using a text editor, create a folder named `output-directory` and a text document named `document.tex` with the following content: ``` tex @@ -7313,8 +7516,10 @@ bug](https://github.com/witiko/markdown/issues). \let\markdownOptionContentBlocks\undefined \let\markdownOptionContentBlocksLanguageMap\undefined \let\markdownOptionDefinitionLists\undefined +\let\markdownOptionEagerCache\undefined \let\markdownOptionFootnotes\undefined \let\markdownOptionFencedCode\undefined +\let\markdownOptionHardLineBreaks\undefined \let\markdownOptionHashEnumerators\undefined \let\markdownOptionHeaderAttributes\undefined \let\markdownOptionHtml\undefined @@ -10512,6 +10717,30 @@ 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. + +% \end{markdown} +% +% \iffalse +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererJekyllDataSequenceEnd{% + \markdownRendererJekyllDataSequenceEndPrototype}% +% \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 @@ -11959,11 +12188,11 @@ pdflatex --shell-escape document.tex % \documentclass{article} \documentclass{article} % \usepackage{markdown} \usepackage{markdown} % \begin{document} \begin{document} -% % ... % ... +% \% ... \% ... % \begin{markdown} \begin{markdown*}{smartEllipses} % _Hello_ **world** ... _Hello_ **world** ... % \end{markdown} \end{markdown*} -% % ... % ... +% \% ... \% ... % \end{document} \end{document} % ``````` % @@ -12054,6 +12283,29 @@ pdflatex --shell-escape document.tex prototypes from plain \TeX{}, load user-contributed themes, and invoke user-defined setup snippets. +#### Setting Lua and plain \TeX{} options from \LaTeX{} + +As a rule of thumb, we can set all Lua options directly from \LaTeX{}. For +example, to set the \Opt{taskLists} Lua option to `true`, we would include the +following code in our \LaTeX{} document: + +``` tex +\markdownSetup{ + taskLists = true, +} +``` + +We can also set all plain \TeX{} options directly from \LaTeX{}. For example, +to set the `\markdownOptionHelperScriptFileName` plain \TeX{} option to +`helper-script.lua`, we would inclde the following code in our \LaTeX{} +document: + +``` tex +\markdownSetup{ + helperScriptFileName = helper-script.lua, +} +``` + % \fi % \par % \begin{markdown} @@ -12064,9 +12316,11 @@ Default token renderer prototypes require \LaTeX{} packages that may clash with other packages used in a document. Additionally, if we redefine token renderers and renderer prototypes ourselves, the default definitions will bring no benefit to us. Using the `plain` package option, we can keep the default -definitions from the plain \TeX{} implementation (see Section -\vref{sec:textokenrendererprototypes}) and prevent the soft \LaTeX{} -prerequisites in Section \vref{sec:latexprerequisites} from being loaded: +definitions from the plain \TeX{} implementation +% (see Section \vref{sec:textokenrendererprototypes}) +and prevent the soft \LaTeX{} prerequisites +% in Section \vref{sec:latexprerequisites} +from being loaded: ``` tex \usepackage[plain]{markdown} @@ -12584,12 +12838,16 @@ The following ordered list will be preceded by roman numerals: \def\markdownOptionContentBlocksLanguageMap{#1}}% \define@key{markdownOptions}{definitionLists}[true]{% \def\markdownOptionDefinitionLists{#1}}% +\define@key{markdownOptions}{eagerCache}[true]{% + \def\markdownOptionEagerCache{#1}}% \define@key{markdownOptions}{footnotes}[true]{% \def\markdownOptionFootnotes{#1}}% \define@key{markdownOptions}{fencedCode}[true]{% \def\markdownOptionFencedCode{#1}}% \define@key{markdownOptions}{jekyllData}[true]{% \def\markdownOptionJekyllData{#1}}% +\define@key{markdownOptions}{hardLineBreaks}[true]{% + \def\markdownOptionHardLineBreaks{#1}}% \define@key{markdownOptions}{hashEnumerators}[true]{% \def\markdownOptionHashEnumerators{#1}}% \define@key{markdownOptions}{headerAttributes}[true]{% @@ -12844,8 +13102,8 @@ The following ordered list will be preceded by roman numerals: % ``` tex % \markdownSetup{ % renderers = { -% link = {#4}, % Render links as the link title. -% emphasis = {\emph{#1}}, % Render emphasized text via `\emph`. +% link = {#4}, \% Render links as the link title. +% emphasis = {\emph{#1}}, \% Render emphasized text via `\emph`. % } % } % ``````` @@ -13016,7 +13274,7 @@ The following ordered list will be preceded by roman numerals: % \markdownSetup{ % rendererPrototypes = { % image = {\includegraphics{#2}}, -% codeSpan = {\texttt{#1}}, % Render inline code via `\texttt`. +% codeSpan = {\texttt{#1}}, \% Render inline code via `\texttt`. % } % } % ``````` @@ -15712,7 +15970,7 @@ function M.writer.new(options) % \end{markdown} % \begin{macrocode} function self.pack(name) - return [[\input ]] .. name .. [[\relax{}]] + return [[\input ]] .. name .. [[\relax]] end % \end{macrocode} % \par @@ -17841,15 +18099,22 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline + larsers.bqstart + larsers.headerstart + larsers.fencestart - ) * parsers.spacechar^0 / writer.space + ) * parsers.spacechar^0 + / (options.hardLineBreaks and writer.linebreak + or writer.space) larsers.OptionalIndent = parsers.spacechar^1 / writer.space larsers.Space = parsers.spacechar^2 * larsers.Endline / writer.linebreak + parsers.spacechar^1 * larsers.Endline^-1 * parsers.eof / "" - + parsers.spacechar^1 * larsers.Endline^-1 - * parsers.optionalspace / writer.space + + parsers.spacechar^1 * larsers.Endline + * parsers.optionalspace + / (options.hardLineBreaks + and writer.linebreak + or writer.space) + + parsers.spacechar^1 * parsers.optionalspace + / writer.space larsers.NonbreakingEndline = parsers.newline * -( -- newline, but not before... @@ -17859,13 +18124,20 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline + larsers.bqstart + larsers.headerstart + larsers.fencestart - ) * parsers.spacechar^0 / writer.nbsp + ) * parsers.spacechar^0 + / (options.hardLineBreaks and writer.linebreak + or writer.nbsp) larsers.NonbreakingSpace = parsers.spacechar^2 * larsers.Endline / writer.linebreak + parsers.spacechar^1 * larsers.Endline^-1 * parsers.eof / "" - + parsers.spacechar^1 * larsers.Endline^-1 - * parsers.optionalspace / writer.nbsp + + parsers.spacechar^1 * larsers.Endline + * parsers.optionalspace + / (options.hardLineBreaks + and writer.linebreak + or writer.nbsp) + + parsers.spacechar^1 * parsers.optionalspace + / writer.nbsp if options.underscores then larsers.Strong = ( parsers.between(parsers.Inline, parsers.doubleasterisks, @@ -18437,19 +18709,30 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline end table.sort(opt_string) local salt = table.concat(opt_string, ",") .. "," .. metadata.version + local output % \end{macrocode} % \begin{markdown} -% Produce the cache file and transform its filename to plain \TeX{} output -% via the \luamref{writer->pack} method. +% If we cache markdown documents, produce the cache file and transform its +% filename to plain \TeX{} output via the \luamref{writer->pack} method. % \end{markdown} % \begin{macrocode} - local name = util.cache(options.cacheDir, input, salt, function(input) - return util.rope_to_string(parse_blocks_toplevel(input)) .. writer.eof - end, ".md" .. writer.suffix) - local output = writer.pack(name) + local function convert(input) + return util.rope_to_string(parse_blocks_toplevel(input)) .. writer.eof + end + if options.eagerCache or options.finalizeCache then + local name = util.cache(options.cacheDir, input, salt, convert, ".md" .. writer.suffix) + output = writer.pack(name) % \end{macrocode} % \begin{markdown} -% If the \Opt{frozenCache} option is enabled, populate the frozen cache in +% Otherwise, return the result of the conversion directly. +% \end{markdown} +% \begin{macrocode} + else + output = convert(input) + end +% \end{macrocode} +% \begin{markdown} +% If the \Opt{finalizeCache} option is enabled, populate the frozen cache in % the file \Opt{frozenCacheFileName} with an entry for markdown document % number \Opt{frozenCacheCounter}. % \end{markdown} @@ -18731,6 +19014,9 @@ end \ifx\markdownOptionDefinitionLists\undefined\else definitionLists = \markdownOptionDefinitionLists, \fi +\ifx\markdownOptionEagerCache\undefined\else + eagerCache = \markdownOptionEagerCache, +\fi \ifx\markdownOptionFinalizeCache\undefined\else finalizeCache = \markdownOptionFinalizeCache, \fi @@ -18742,6 +19028,9 @@ end \ifx\markdownOptionFencedCode\undefined\else fencedCode = \markdownOptionFencedCode, \fi +\ifx\markdownOptionHardLineBreaks\undefined\else + hardLineBreaks = \markdownOptionHardLineBreaks, +\fi \ifx\markdownOptionHashEnumerators\undefined\else hashEnumerators = \markdownOptionHashEnumerators, \fi @@ -19226,7 +19515,28 @@ end % % \end{markdown} % \begin{macrocode} -\def\markdownLuaExecute#1{\directlua{local print = tex.print #1}}% +\begingroup +% \end{macrocode} +% \begin{markdown} +% Swap the category code of the backslash symbol and the pipe symbol, so that +% we may use the backslash symbol freely inside the Lua code. +% \end{markdown} +% \begin{macrocode} + \catcode`|=0% + \catcode`\\=12% + |gdef|markdownLuaExecute#1{% + |directlua{% + local function print(input) + local output = {} + for line in input:gmatch("[^\r\n]+") do + table.insert(output, line) + end + tex.print(output) + end + #1 + }% + }% +|endgroup \fi % \end{macrocode} % \par @@ -19745,8 +20055,17 @@ end \ifx\empty#4\empty\else \caption{#4}% \fi - \end{table}}{% - \markdownInput{#3}}}, + \end{table}% + }{% + \ifthenelse{\equal{#1}{tex}}{% + \catcode`\%=14\relax + \input #3\relax + \catcode`\%=12\relax + }{% + \markdownInput{#3}% + }% + }% + }, image = {% \begin{figure}% \begin{center}% @@ -20603,24 +20922,50 @@ end % The \mref{startmarkdown} and \mref{stopmarkdown} macros are implemented using the % \mref{markdownReadAndConvert} macro. % +% In Knuth's \TeX, trailing spaces are removed very early on when a line is +% being put to the input buffer.~[@knuth86b, sec. 31]. According to +% @eijkhout92 [sec. 2.2], this is because ``these spaces are hard to see in +% an editor''. At the moment, there is no option to suppress this behavior in +% (Lua)\TeX, but \Hologo{ConTeXt} MkIV funnels all input through its own input +% handler. This makes it possible to suppress the removal of trailing spaces +% in \Hologo{ConTeXt} MkIV and therefore to insert hard line breaks into +% markdown text. +% % \end{markdown} % \begin{macrocode} -\begingroup -% \end{macrocode} -% \begin{markdown} -% Locally swap the category code of the backslash symbol with the pipe symbol. -% This is required in order that all the special symbols that appear in the -% first argument of the `markdownReadAndConvert` macro have the category code -% *other*. -% \end{markdown} -% \begin{macrocode} - \catcode`\|=0% - \catcode`\\=12% - |gdef|startmarkdown{% - |markdownReadAndConvert{\stopmarkdown}% - {|stopmarkdown}}% - |gdef|stopmarkdown{|markdownEnd}% -|endgroup +\ifx\startluacode\undefined % MkII + \begingroup + \catcode`\|=0% + \catcode`\\=12% + |gdef|startmarkdown{% + |markdownReadAndConvert{\stopmarkdown}% + {|stopmarkdown}}% + |gdef|stopmarkdown{% + |markdownEnd}% + |endgroup +\else % MkIV + \startluacode + document.markdown_buffering = false + local function preserve_trailing_spaces(line) + if document.markdown_buffering then + line = line:gsub("[ \t][ \t]$", "\t\t") + end + return line + end + resolvers.installinputlinehandler(preserve_trailing_spaces) + \stopluacode + \begingroup + \catcode`\|=0% + \catcode`\\=12% + |gdef|startmarkdown{% + |ctxlua{document.markdown_buffering = true}% + |markdownReadAndConvert{\stopmarkdown}% + {|stopmarkdown}}% + |gdef|stopmarkdown{% + |ctxlua{document.markdown_buffering = false}% + |markdownEnd}% + |endgroup +\fi % \end{macrocode} % \par % \begin{markdown} |