summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/markdown/markdown.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/markdown/markdown.dtx')
-rw-r--r--Master/texmf-dist/source/generic/markdown/markdown.dtx441
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}