diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/markdown/markdown.dtx')
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 7066 |
1 files changed, 6202 insertions, 864 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx index 03c95872f4e..0222985095c 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.dtx +++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx @@ -1,22 +1,14 @@ % \iffalse %<*driver> \documentclass{ltxdockit} -\usepackage{btxdockit} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage[american]{babel} -\usepackage{microtype} -\usepackage{amsmath} -\usepackage{fancyvrb} -\usepackage{hologo} -\usepackage{xcolor} -\usepackage{doc} +\usepackage{amsmath,btxdockit,doc,fancyvrb,hologo,microtype,minted,xcolor} % Set up the style. \emergencystretch=1em -\RecustomVerbatimEnvironment - {Verbatim}{Verbatim} - {gobble=2,frame=single} +\fvset{gobble=0,frame=single} \setcounter{secnumdepth}{4} \addtokomafont{title}{\sffamily} \addtokomafont{paragraph}{\spotcolor} @@ -37,15 +29,16 @@ \newcommand\m[1]{% A TeX macro reference \hyperref[macro:#1]{\textcolor{spot}{\cs{#1}}}} \newcommand\envmdef[1]{% A TeX macro definition - \phantomsection\label{environment:#1}\textcolor{spot}{\t`#1`}} + \phantomsection\label{environment:#1}\t`#1`} \newcommand\envm[1]{% A LaTeX environment reference - \hyperref[environment:#1]{\textcolor{spot}{\t`#1`}}} + \hyperref[environment:#1]{\t`#1`}} \newcommand\luamdef[1]{% A Lua object / method definition - \phantomsection\label{lua:#1}\textcolor{spot}{\t`#1`}} + \phantomsection\label{lua:#1}\t`#1`} \newcommand\luam[1]{% A Lua object / method reference \hyperref[lua:#1]{\t`#1`}} -\def\t`#1`{% Inline code +\def\inline#1{% Inline code \textcolor{spot}{\text{\texttt{#1}}}} +\def\t`#1`{\inline{#1}} \newcommand\Optitem[2][]{\penalty -1000\relax % An option item definition \phantomsection\label{opt:#2}\optitem[#1]{#2}} \newcommand\Valitem[2][]{\penalty -1000\relax % A value item definition @@ -55,6 +48,20 @@ \newcommand\acro[1]{% An acronym \textsc{#1}} +% Set up markdown. +\usepackage[ + citations, + definitionLists, + fencedCode, + hybrid, + html, + stripPercentSigns, + underscores=false]{markdown} +\markdownSetup{ + renderers = { + codeSpan = {\inline{#1}}, + link = {#1\footnote{See \url{#3}.}}}} + % Set up the catcodes. \catcode`\_=12 % We won't be typesetting math and Lua contains lots of `_`. @@ -65,7 +72,7 @@ url={https://github.com/witiko/markdown}, author={Vít Novotný}, email={witiko@mail.muni.cz}, - revision={\input VERSION}, + revision=\markdownVersion, date={\today}} \hypersetup{% pdftitle={A Markdown Interpreter for \TeX{}}, @@ -75,701 +82,4874 @@ % Set up the bibliography. \usepackage{filecontents} \begin{filecontents}{markdown.bib} - @online{sotkov17, - author = {Sotkov, Anton}, - title = {File transclusion syntax for Markdown}, - date = {2017-01-19}, - url = {https://github.com/iainc/Markdown-Content-Blocks}, - urldate = {2018-01-08}} - @book{luatex17, - author = {{Lua\TeX{} development team}}, - title = {Lua\TeX{} reference manual}, - year = {2017}, - month = {2}, - url = {http://www.luatex.org/svn/trunk/manual/luatex.pdf}, - urldate = {2018-01-08}} - @book{latex17, - author = {Braams, Johannes and Carlisle, David and Jeffrey, Alan and - Lamport, Leslie and Mittelbach, Frank and Rowley, Chris and - Schöpf, Rainer}, - title = {The \Hologo{LaTeX2e} Sources}, - date = {2017-04-15}, - url = {http://mirrors.ctan.org/macros/latex/base/source2e.pdf}, - urldate = {2018-01-08}} - @book{ierusalimschy13, - author = {Ierusalimschy, Roberto}, - year = {2013}, - title = {Programming in Lua}, - edition = {3}, - isbn = {978-85-903798-5-0}, - pagetotal = {xviii, 347}, - location = {Rio de Janeiro}, - publisher = {PUC-Rio}} - @book{knuth86, - author = {Knuth, Donald Ervin}, - year = {1986}, - title = {The \TeX{}book}, - edition = {3}, - isbn = {0-201-13447-0}, - pagetotal = {ix, 479}, - publisher = {Addison-Wesley}} +@online{sotkov17, + author = {Sotkov, Anton}, + title = {File transclusion syntax for Markdown}, + date = {2017-01-19}, + url = {https://github.com/iainc/Markdown-Content-Blocks}, + urldate = {2018-01-08}} +@book{luatex17, + author = {{Lua\TeX{} development team}}, + title = {Lua\TeX{} reference manual}, + year = {2017}, + month = {2}, + url = {http://www.luatex.org/svn/trunk/manual/luatex.pdf}, + urldate = {2018-01-08}} +@book{latex17, + author = {Braams, Johannes and Carlisle, David and Jeffrey, Alan and + Lamport, Leslie and Mittelbach, Frank and Rowley, Chris and + Schöpf, Rainer}, + title = {The \Hologo{LaTeX2e} Sources}, + date = {2017-04-15}, + url = {http://mirrors.ctan.org/macros/latex/base/source2e.pdf}, + urldate = {2018-01-08}} +@book{mittelbach17, + author = {Mittelbach, Frank}, + title = {The \texttt{doc} and \texttt{shortvrb} Packages}, + date = {2017-04-15}, + url = {http://mirrors.ctan.org/macros/latex/base/doc.pdf}, + urldate = {2018-02-19}} +@online{novotny15, + author = {Novotný, Vít}, + year = {2015}, + title = {TeXový interpret jazyka Markdown (markdown.sty)}, + location = {Brno, Czech Republic}, + publisher = {Masaryk University}, + url = {https://www.muni.cz/en/research/projects/32984}, + urldate = {2018-02-19}} +@book{ierusalimschy13, + author = {Ierusalimschy, Roberto}, + year = {2013}, + title = {Programming in Lua}, + edition = {3}, + isbn = {978-85-903798-5-0}, + pagetotal = {xviii, 347}, + location = {Rio de Janeiro}, + publisher = {PUC-Rio}} +@book{knuth86, + author = {Knuth, Donald Ervin}, + year = {1986}, + title = {The \TeX{}book}, + edition = {3}, + isbn = {0-201-13447-0}, + pagetotal = {ix, 479}, + publisher = {Addison-Wesley}} \end{filecontents} \usepackage[ backend=biber, - style=iso-numeric, + style=numeric, sorting=none, autolang=other, sortlocale=auto]{biblatex} \addbibresource{markdown.bib} \begin{document} - \printtitlepage - \tableofcontents - \DocInput{markdown.dtx} - \printbibliography +\printtitlepage +\tableofcontents +\DocInput{markdown.dtx} +\printbibliography \end{document} %</driver> +%<*manual-css> + +html { + font-size: 100%; + overflow-y: scroll; + -webkit-text-size-adjust: 100%; + -ms-text-size-adjust: 100%; +} + +body { + color: #444; + font-family: Georgia, Palatino, 'Palatino Linotype', Times, 'Times New Roman', serif; + font-size: 12px; + line-height: 1.7; + padding: 1em; + margin: auto; + max-width: 42em; + background: #fefefe; +} + +a { + color: #0645ad; +} + +a:visited { + color: #0b0080; +} + +a:hover { + color: #06e; +} + +a:active { + color: #faa700; +} + +a:focus { + outline: thin dotted; +} + +*::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +*::selection { + background: rgba(255, 255, 0, 0.3); + color: #000; +} + +a::-moz-selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +a::selection { + background: rgba(255, 255, 0, 0.3); + color: #0645ad; +} + +p { + margin: 1em 0; +} + +img { + max-width: 100%; +} + +h1, h2, h3, h4, h5, h6 { + color: #111; + line-height: 125%; + margin-top: 2em; + font-weight: normal; +} + +h4, h5, h6 { + font-weight: bold; +} + +h1 { + font-size: 2.5em; +} + +h2 { + font-size: 2em; +} + +h3 { + font-size: 1.5em; +} + +h4 { + font-size: 1.2em; +} + +h5 { + font-size: 1em; +} + +h6 { + font-size: 0.9em; +} + +blockquote { + color: #666666; + margin: 0; + padding-left: 3em; + border-left: 0.5em #EEE solid; +} + +hr { + display: block; + height: 2px; + border: 0; + border-top: 1px solid #aaa; + border-bottom: 1px solid #eee; + margin: 1em 0; + padding: 0; +} + +pre, code, kbd, samp { + color: #000; + font-family: monospace, monospace; + _font-family: 'courier new', monospace; + font-size: 0.98em; +} + +pre { + white-space: pre; + white-space: pre-wrap; + word-wrap: break-word; +} + +b, strong { + font-weight: bold; +} + +dfn { + font-style: italic; +} + +ins { + background: #ff9; + color: #000; + text-decoration: none; +} + +mark { + background: #ff0; + color: #000; + font-style: italic; + font-weight: bold; +} + +sub, sup { + font-size: 75%; + line-height: 0; + position: relative; + vertical-align: baseline; +} + +sup { + top: -0.5em; +} + +sub { + bottom: -0.25em; +} + +ul, ol { + margin: 1em 0; + padding: 0 0 0 2em; +} + +li p:last-child { + margin-bottom: 0; +} + +ul ul, ol ol { + margin: .3em 0; +} + +dl { + margin-bottom: 1em; +} + +dt { + font-weight: bold; + margin-bottom: .8em; +} + +dd { + margin: 0 0 .8em 2em; +} + +dd:last-child { + margin-bottom: 0; +} + +img { + border: 0; + -ms-interpolation-mode: bicubic; + vertical-align: middle; +} + +figure { + display: block; + text-align: center; + margin: 1em 0; +} + +figure img { + border: none; + margin: 0 auto; +} + +figcaption { + font-size: 0.8em; + font-style: italic; + margin: 0 0 .8em; +} + +table { + margin-bottom: 2em; + border-bottom: 1px solid #ddd; + border-right: 1px solid #ddd; + border-spacing: 0; + border-collapse: collapse; +} + +table th { + padding: .2em 1em; + background-color: #eee; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; +} + +table td { + padding: .2em 1em; + border-top: 1px solid #ddd; + border-left: 1px solid #ddd; + vertical-align: top; +} + +.author { + font-size: 1.2em; + text-align: center; +} + +@media only screen and (min-width: 480px) { + body { + font-size: 14px; + } +} +@media only screen and (min-width: 768px) { + body { + font-size: 16px; + } +} +@media print { + * { + background: transparent !important; + color: black !important; + filter: none !important; + -ms-filter: none !important; + } + + body { + font-size: 12pt; + max-width: 100%; + } + + a, a:visited { + text-decoration: underline; + } + + hr { + height: 1px; + border: 0; + border-bottom: 1px solid black; + } + + a[href]:after { + content: " (" attr(href) ")"; + } + + abbr[title]:after { + content: " (" attr(title) ")"; + } + + .ir a:after, a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + + pre, blockquote { + border: 1px solid #999; + padding-right: 1em; + page-break-inside: avoid; + } + + tr, img { + page-break-inside: avoid; + } + + img { + max-width: 100% !important; + } + + @page :left { + margin: 15mm 20mm 15mm 10mm; +} + + @page :right { + margin: 15mm 10mm 15mm 20mm; +} + + p, h2, h3 { + orphans: 3; + widows: 3; + } + + h2, h3 { + page-break-after: avoid; + } +} + +%</manual-css> +%<*manual> + +--- +title: Markdown Package User Manual +author: Vít Novotný +--- + % \fi -% -% \section{Introduction} -% This document is a reference manual for the \pkg{Markdown} package. It is -% split into three sections. This section explains the purpose and the -% background of the package and outlines its prerequisites. Section -% \ref{sec:interfaces} describes the interfaces exposed by the package along -% with usage notes and examples. It is aimed at the user of the package. -% Section \ref{sec:implementation} describes the implementation of the package. -% It is aimed at the developer of the package and the curious user. -% -% \subsection{About \pkg{Markdown}} -% The \pkg{Markdown} package provides facilities for the conversion of markdown -% markup to plain \TeX{}. These are provided both in the form of a Lua module -% and in the form of plain \TeX{}, \LaTeX{}, and \Hologo{ConTeXt} macro -% packages that enable the direct inclusion of markdown documents inside \TeX{} -% documents. -% -% Architecturally, the package consists of the \pkg{Lunamark} v0.5.0 Lua module -% by John MacFarlane, which was slimmed down and rewritten for the needs of the -% package. On top of \pkg{Lunamark} sits code for the plain \TeX{}, \LaTeX{}, -% and \Hologo{ConTeXt} formats by Vít Novotný. -% +% \par +% \begin{markdown} + +<link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" /> + +Introduction +============ +The [Markdown package][pkg] converts [markdown][] markup to TeX commands. The +functionality is provided both as a Lua module, and as plain TeX, LaTeX, and +ConTeXt macro packages that can be used to directly typeset TeX documents +containing markdown markup. Unlike other convertors, the Markdown package +makes it easy to redefine how each and every markdown element is rendered. +Creative abuse of the markdown syntax is encouraged. <i class="em em-wink"></i> + + [markdown]: https://daringfireball.net/projects/markdown/basics/ + (Daring Fireball: Markdown Basics) + [pkg]: https://ctan.org/pkg/markdown + (CTAN: Package markdown) + +% This document is a technical documentation for the \pkg{Markdown} package. It +% consists of three sections. This section introduces the package and outlines +% its prerequisites. Section \ref{sec:interfaces} describes the interfaces +% exposed by the package. Section \ref{sec:implementation} describes the +% implementation of the package. The technical documentation contains only a +% limited number of tutorials and code examples. You can find more of these in +% the [user manual.][manual] +% +% [manual]: http://mirrors.ctan.org/macros/generic/markdown/markdown.html +% +% \end{markdown} % \iffalse -%<*lua> + +This document is a user manual for the [Markdown package][pkg]. It provides +beginner tutorials and code examples. For an in-depth description of the +package requirements, interfaces, and implementation, please refer to the +[technical documentation][techdoc]. + + [techdoc]: http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf + (A Markdown Interpreter for TeX) + +%</manual> +%<*lua,lua-cli> % \fi % \begin{macrocode} local metadata = { - version = "2.5.5", + version = "2.5.6", comment = "A module for the conversion from markdown to plain TeX", author = "John MacFarlane, Hans Hagen, Vít Novotný", - copyright = "2009-2016 John MacFarlane, Hans Hagen; " .. - "2016-2018 Vít Novotný", + copyright = {"2009-2016 John MacFarlane, Hans Hagen", + "2016-2018 Vít Novotný"}, license = "LPPL 1.3" } + +% \end{macrocode} +% \iffalse +%</lua,lua-cli> +%<*lua> +% \fi +% \begin{macrocode} if not modules then modules = { } end modules['markdown'] = metadata % \end{macrocode} +% \par +% \begin{markdown} +% +% Feedback +%--------- +% Please use the \pkg{Markdown} project page on +% [GitHub](https://github.com/witiko/markdown/issues) to report bugs and submit +% feature requests. If you do not want to report a bug or request a feature but +% are simply in need of assistance, you might want to consider posting your +% question on the [\TeX-\LaTeX{} Stack Exchange.](https://tex.stackexchange.com) +% +% Acknowledgements +%----------------- +% The Lunamark Lua module provides speedy markdown parsing for the package. I +% would like to thank John Macfarlane, the creator of Lunamark, for releasing +% Lunamark under a permissive license. +% +% Funding by the the Faculty of Informatics at the Masaryk~University +% in~Brno~[@novotny15] is gratefully acknowledged. +% +% The \TeX{} implementation of the package draws inspiration from several +% sources including the source code of \Hologo{LaTeX2e}, the \pkg{minted} +% package by Geoffrey M. Poore -- which likewise tackles the issue of +% interfacing with an external interpreter from \TeX{}, the \pkg{filecontents} +% package by Scott Pakin, and others. +% +% \end{markdown} +% \iffalse +%</lua> +%<*manual> + +Requirements +------------ + +The package requires a working TeX distribution. [TeX Live][] ≥ 2013 is known to +work and so are recent installation of [MikTeX][]. If you are using a minimal +installation of a TeX distribution, please consult the +[technical documentation][techdoc] for a detailed list of required packages. + + [TeX Live]: https://www.tug.org/texlive/ (TeX Live - TeX Users Group) + [MikTeX]: https://miktex.org/ (Home - MiKTeXorg) + +Installation +------------ + +The package comes pre-installed with [TeX Live][] ≥ 2016 and with recent +installations of [MikTeX][]. Unless you explicitly wish to use the latest +version of the package, you are encouraged to skip this step. + +To install the package, first download the package from the repository +using Git: +``` sh +git clone https://github.com/witiko/markdown +`````` +Next, enter the directory named `markdown` and interpret the file named +`markdown.ins` file using a Unicode-aware TeX engine, such as XeTeX or +LuaTeX: +``` sh +cd markdown +luatex markdown.ins +`````` +This should produce the following files: + + * `markdown.lua` – the Lua module, + * `markdown-cli.lua` – the Lua command-line interface, + * `markdown.tex` – the plain TeX macro package, + * `markdown.sty` – the LaTeX package, and + * `t-markdown.tex` – the ConTeXt module. + +### Local installation + +To perform a local installation, place the above files into your TeX directory +structure. This is generally where the individual files should be placed: + + * `<TEXMF>/tex/luatex/markdown/markdown.lua` + * `<TEXMF>/scripts/markdown/markdown-cli.lua` + * `<TEXMF>/tex/generic/markdown/markdown.tex` + * `<TEXMF>/tex/latex/markdown/markdown.sty` + * `<TEXMF>/tex/context/third/markdown/t-markdown.tex` + +where `<TEXMF>` corresponds to a root of your TeX distribution, such as +`/usr/share/texmf` and `~/texmf` on UN\*X systems or +`C:\Users\<YOUR␣USERNAME>\texmf` on Windows systems. When in doubt, +consult the manual of your TeX distribution. + +### Portable installation ### + +Alternatively, you can also store the above files in the same folder as your +TeX document and distribute them together. This way your document can be +portably typeset on legacy TeX distributions. + +%</manual> +%<*lua> +% \fi +% \par +% \begin{markdown} +% +% Requirements +%------------- % -% \subsection{Feedback} -% Please use the \pkg{markdown} project page on -% GitHub\footnote{\url{https://github.com/witiko/markdown/issues}} to report -% bugs and submit feature requests. Before making a feature request, please -% ensure that you have thoroughly studied this manual. If you do not want to -% report a bug or request a feature but are simply in need of assistance, you -% might want to consider posting your question on the \TeX-\LaTeX{} Stack -% Exchange\footnote{\url{https://tex.stackexchange.com}}. -% -% \subsection{Acknowledgements} -% I would like to thank the Faculty of Informatics at the Masaryk University in -% Brno for providing me with the opportunity to work on this package alongside -% my studies. I would also like to thank the creator of the Lunamark Lua -% module, John Macfarlane, for releasing Lunamark under a permissive license -% that enabled its inclusion into the package. -% -% The \TeX{} part of the package draws inspiration from several sources -% including the source code of \Hologo{LaTeX2e}, the \pkg{minted} package by -% Geoffrey M. Poore -- which likewise tackles the issue of interfacing with an -% external interpreter from \TeX, the \pkg{filecontents} package by Scott -% Pakin, and others. -% -% \subsection{Prerequisites} % This section gives an overview of all resources required by the package. % -% \subsubsection{Lua Prerequisites}\label{sec:luaprerequisites} +%### Lua Requirements +% \label{sec:luaprerequisites} % The Lua part of the package requires that the following Lua modules are % available from within the Lua\TeX{} engine: -% \begin{description} -% \item[\pkg{LPeg${}\geq{}$0.10}] A pattern-matching library for the writing -% of recursive descent parsers via the Parsing Expression Grammars -% (\acro{peg}s). It is used by the \pkg{Lunamark} library to parse the -% markdown input. \pkg{LPeg${}\geq{}$0.10} is included in -% Lua\TeX${}\geq{}$0.72.0 (\TeX Live${}\geq{}2013$). +% +% \pkg{LPeg${}\geq{}$0.10} +% +%: A pattern-matching library for the writing of recursive descent parsers +% via the Parsing Expression Grammars (\acro{peg}s). It is used by the +% \pkg{Lunamark} library to parse the markdown input. +% \pkg{LPeg${}\geq{}$0.10} is included in Lua\TeX${}\geq{}$0.72.0 (\TeX +% Live${}\geq{}2013$). +% +% \end{markdown} % \begin{macrocode} local lpeg = require("lpeg") % \end{macrocode} -% \item[\pkg{Selene Unicode}] A library that provides support for the -% processing of wide strings. It is used by the \pkg{Lunamark} library to -% cast image, link, and footnote tags to the lower case. \pkg{Selene -% Unicode} is included in all releases of Lua\TeX{} (\TeX -% Live${}\geq{}2008$). +% \par +% \begin{markdown} +% +% \pkg{Selene Unicode} +% +%: A library that provides support for the processing of wide strings. It is +% used by the \pkg{Lunamark} library to cast image, link, and footnote tags +% to the lower case. \pkg{Selene Unicode} is included in all releases of +% Lua\TeX{} (\TeX Live${}\geq{}2008$). +% +% \end{markdown} % \begin{macrocode} local unicode = require("unicode") % \end{macrocode} -% \item[\pkg{MD5}] A library that provides \acro{md5} crypto functions. It is -% used by the \pkg{Lunamark} library to compute the digest of the input for -% caching purposes. \pkg{MD5} is included in all releases of Lua\TeX{} -% (\TeX Live${}\geq{}2008$). +% \par +% \begin{markdown} +% +% \pkg{MD5} +% +%: A library that provides \acro{md5} crypto functions. It is used by the +% \pkg{Lunamark} library to compute the digest of the input for caching +% purposes. \pkg{MD5} is included in all releases of Lua\TeX{} (\TeX +% Live${}\geq{}2008$). +% +% \end{markdown} % \begin{macrocode} local md5 = require("md5") % \end{macrocode} -% \end{description} +% \par +% \begin{markdown} +% % All the abovelisted modules are statically linked into the current version of -% the Lua\TeX{} engine (see \cite[Section~3.3]{luatex17}). +% the Lua\TeX{} engine~[@luatex17, Section 3.3]. % +% \end{markdown} % \iffalse %</lua> %<*tex> % \fi -% \subsubsection{Plain \TeX{} Prerequisites}\label{sec:texprerequisites} +% \par +% \begin{markdown} +% +%### Plain \TeX{} Requirements +% \label{sec:texprerequisites} % The plain \TeX{} part of the package requires that the plain \TeX{} % format (or its superset) is loaded, all the Lua prerequisites (see % Section \ref{sec:luaprerequisites}), and the following Lua module: -% \begin{description} -% \item[\pkg{Lua File System}] 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 -% \m{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$). +% +% \pkg{Lua File System} +% +%: 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 \m{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$). % % The plain \TeX{} code makes use of the \luam{isdir} method that was added -% to the \pkg{Lua File System} library by the Lua\TeX{} engine developers -% (see \cite[Section~3.2]{luatex17}). -% \end{description} +% to the \pkg{Lua File System} library by the Lua\TeX{} engine +% developers~[@luatex17, Section 3.2]. +% % The \pkg{Lua File System} module is statically linked into the Lua\TeX{} -% engine (see \cite[Section~3.3]{luatex17}). +% engine~[@luatex17, Section~3.3]. % -% The plain \TeX{} part of the package also requires that either the Lua\TeX{} +% Unless you convert markdown documents to \TeX{} manually using the Lua +% command-line interface (see Section~\ref{sec:lua-cli-interface}), the plain +% \TeX{} part of the package will require that either the Lua\TeX{} % \m{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 \m{markdownMode} macro, then note that -% unless your \TeX{} engine is globally configured to enable shell access, you -% will need to provide the \t`-shell-escape` parameter to your engine when -% typesetting a document. +% you enforce the use of shell using the \m{markdownMode} macro, then unless +% your \TeX{} engine is globally configured to enable shell access, you will +% need to provide the `-shell-escape` parameter to your engine when typesetting +% a document. % +% \end{markdown} % \iffalse %</tex> %<*latex> % \fi -% \subsubsection{\LaTeX{} Prerequisites}\label{sec:latexprerequisites} +% \par +% \begin{markdown} +% +%### \LaTeX{} Requirements +% \label{sec:latexprerequisites} % The \LaTeX{} part of the package requires that the \Hologo{LaTeX2e} format is % loaded, +% \end{markdown} % \begin{macrocode} \NeedsTeXFormat{LaTeX2e}% % \end{macrocode} +% \begin{markdown} % all the plain \TeX{} prerequisites (see Section \ref{sec:texprerequisites}), % and the following \Hologo{LaTeX2e} packages: -% \begin{description} -% \item[\pkg{keyval}] A package that enables the creation of parameter sets. -% This package is used to provide the \m{markdownSetup} macro, the package -% options processing, as well as the parameters of the \envm{markdown*} -% \LaTeX{} environment. +% +% \pkg{keyval} +% +%: A package that enables the creation of parameter sets. This package is +% used to provide the \m{markdownSetup} macro, the package options +% processing, as well as the parameters of the \envm{markdown*} \LaTeX{} +% environment. +% +% \end{markdown} % \begin{macrocode} \RequirePackage{keyval} % \end{macrocode} -% \item[\pkg{url}] A package that provides the \m{url} macro for the -% typesetting of \acro{url}s. It is used to provide the default token renderer -% prototype (see Section \ref{sec:texrendererprototypes}) for links. +% \par +% \begin{markdown} +% +% \pkg{url} +% +%: A package that provides the \m{url} macro for the typesetting of +% \acro{url}s. It is used to provide the default token renderer prototype +% (see Section \ref{sec:texrendererprototypes}) for links. +% +% \end{markdown} % \begin{macrocode} \RequirePackage{url} % \end{macrocode} -% \item[\pkg{graphicx}] A package that provides the \m{includegraphics} macro for -% the typesetting of images. It is used to provide the corresponding -% default token renderer prototype (see Section -% \ref{sec:texrendererprototypes}). +% \par +% \begin{markdown} +% +% \pkg{graphicx} +% +%: A package that provides the \m{includegraphics} macro for the typesetting +% of images. It is used to provide the corresponding default token renderer +% prototype (see Section \ref{sec:texrendererprototypes}). +% +% \end{markdown} % \begin{macrocode} \RequirePackage{graphicx} % \end{macrocode} -% \item[\pkg{paralist}] A package that provides the \envm{compactitem}, -% \envm{compactenum}, and \envm{compactdesc} macros for the -% typesetting of tight bulleted lists, ordered lists, and definition lists. -% It is used to provide the corresponding default token renderer prototypes -% (see Section \ref{sec:texrendererprototypes}). -% \item[\pkg{ifthen}] A package that provides a concise syntax for the -% inspection of macro values. It is used to determine whether or not the -% \pkg{paralist} package should be loaded based on the user options. +% \par +% \begin{markdown} +% +% \pkg{paralist} +% +%: A package that provides the \envm{compactitem}, \envm{compactenum}, and +% \envm{compactdesc} macros for the typesetting of tight bulleted lists, +% ordered lists, and definition lists. It is used to provide the +% corresponding default token renderer prototypes (see Section +% \ref{sec:texrendererprototypes}). +% +% \pkg{ifthen} +% +%: A package that provides a concise syntax for the inspection of macro +% values. It is used to determine whether or not the \pkg{paralist} package +% should be loaded based on the user options. +% +% \end{markdown} % \begin{macrocode} \RequirePackage{ifthen} % \end{macrocode} -% \item[\pkg{fancyvrb}] A package that provides the \m{VerbatimInput} macros -% for the verbatim inclusion of files containing code. It is used to -% provide the corresponding default token renderer prototype (see Section +% \par +% \begin{markdown} +% +% \pkg{fancyvrb} +% +%: A package that provides the \m{VerbatimInput} macros for the verbatim +% inclusion of files containing code. It is used to provide the +% corresponding default token renderer prototype (see Section % \ref{sec:texrendererprototypes}). +% +% \end{markdown} % \begin{macrocode} \RequirePackage{fancyvrb} % \end{macrocode} -% \item[\pkg{csvsimple}] A package that provides the default token renderer -% prototype for iA\,Writer content blocks with the \acro{csv} filename -% extension (see Section \ref{sec:texrendererprototypes}). +% \par +% \begin{markdown} +% +% \pkg{csvsimple} +% +%: A package that provides the default token renderer prototype for +% iA\,Writer content blocks with the \acro{csv} filename extension (see +% Section \ref{sec:texrendererprototypes}). +% +% \end{markdown} % \begin{macrocode} \RequirePackage{csvsimple} % \end{macrocode} -% \end{description} -% % \iffalse %</latex> %<*context> % \fi -% \subsubsection{\Hologo{ConTeXt} prerequisites} +% \par +% \begin{markdown} +% +%### \Hologo{ConTeXt} prerequisites % The \Hologo{ConTeXt} part of the package requires that either the Mark II or % the Mark IV format is loaded, all the plain \TeX{} prerequisites (see % Section \ref{sec:texprerequisites}), and the following \Hologo{ConTeXt} % modules: -% \begin{description} -% \item[\pkg{m-database}] A module that provides the default token renderer -% prototype for iA\,Writer content blocks with the \acro{csv} filename -% extension (see Section \ref{sec:texrendererprototypes}). -% \end{description} -% -% \section{User Guide}\label{sec:interfaces} -% This part of the manual describes the interfaces exposed by the package +% +% \pkg{m-database} +% +%: A module that provides the default token renderer prototype for +% iA\,Writer content blocks with the \acro{csv} filename extension (see +% Section \ref{sec:texrendererprototypes}). +% +% Interfaces +%=========== +% \label{sec:interfaces} +% This part of the documentation describes the interfaces exposed by the package % along with usage notes and examples. It is aimed at the user of the package. % % Since neither \TeX{} nor Lua provide interfaces as a language construct, the % separation to interfaces and implementations is purely abstract. It serves as -% a means of structuring this manual and as a promise to the user that if they -% only access the package through the interfaces, the future versions of the -% package should remain backwards compatible. +% a means of structuring this documentation and as a promise to the user that +% if they only access the package through the interface, the future minor +% versions of the package should remain backwards compatible. % +% \end{markdown} % \iffalse %</context> +%<*manual> + +First document +-------------- + +In this section, we will take the necessary steps to typeset our first markdown +document in TeX. This will serve as our first hands-on experience with the +package and also as a reassurance that the package has been correctly installed. + +### Using Lua + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input hello +\bye +``````` + +#### Using the Lua module + +Using a text editor, create a text document named `hello.lua` with the +following content: +``` lua +#!/usr/bin/env texlua +local kpse = require("kpse") +kpse.set_program_name("luatex") +local markdown = require("markdown") +local convert = markdown.new() +print(convert("Hello *world*!")) +``````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua hello.lua > hello.tex +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” Invoking pdfTeX should have the same effect: +``` sh +texlua hello.lua > hello.tex +pdftex document.tex +`````` + +#### Using the Lua CLI + +Using a text editor, create a text document named `hello.md` with the +following content: +``` md +Hello *world*! +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- hello.md hello.tex +luatex document.tex +`````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + + [Kpathsea]: https://tug.org/kpathsea/ (Kpathsea - TeX Users Group) + +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +texlua <CLI␣PATHNAME> -- hello.md hello.tex +pdftex document.tex +`````` + +### Using plain TeX + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\markdownBegin +Hello *world*! +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” Invoking pdfTeX should have the same effect: +``` sh +pdftex --shell-escape document.tex +``````` + +### Using LaTeX + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage{markdown} +\begin{document} +\begin{markdown} +Hello *world*! +\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 text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +pdflatex --shell-escape document.tex +`````` + +*** + +As the next step, try typesetting the example documents distributed along with +the Markdown package: +``` sh +git clone https://github.com/witiko/markdown +cd markdown/examples +lualatex latex.tex +`````` +A PDF document named `latex.pdf` should be produced. Open the text documents +`latex.tex` and `example.md` in a text editor to see how the example documents +are structured. Try changing the documents and typesetting them as follows: +``` sh +lualatex latex.tex +`````` +to see the effect of your changes. + +### Using ConTeXt + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext +\startmarkdown +Hello *world*! +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” Invoking pdfTeX should have the same effect: +``` sh +texexec --passon=--shell-escape document.tex +`````` + +*** + +As the next step, try typesetting the example documents distributed along with +the Markdown package: +``` sh +git clone https://github.com/witiko/markdown +cd markdown/examples +context context.tex +`````` +A PDF document named `context.pdf` should be produced. Open the text documents +`context.tex` and `example.md` in a text editor to see how the example documents +are structured. Try changing the documents and typesetting them as follows: +``` sh +context context.tex +`````` +to see the effect of your changes. + +Examples +======== + +This section will show how to use the package by example. + +%</manual> +%<*lua> +% \fi +% \par +% \begin{markdown} +% +% Lua Interface +%-------------- +% \label{sec:luainterface} +% +% \iffalse +%</lua> +%<*manual> + +Lua +--- + +The Lua part of the package makes it possible to convert a markdown document +into TeX commands and typeset it later when convenient. Although the typical +user will not find this terribly useful and will instead use the plain TeX, +LaTeX, and ConTeXt macro packages to convert and typeset the markdown documents +in a single step, they will still benefit from learning the options that +control the behavior of the Lua parser. + +%</manual> %<*lua> % \fi -% \subsection{Lua Interface}\label{sec:luainterface} +% % The Lua interface provides the conversion from \acro{utf}-\oldstylenums8 % encoded markdown to plain \TeX{}. This interface is used by the plain \TeX{} % implementation (see Section \ref{sec:teximplementation}) and will be of % interest to the developers of other packages and Lua modules. % -% The Lua interface is implemented by the \t`markdown` Lua module. +% The Lua interface is implemented by the `markdown` Lua module. % +% \end{markdown} % \begin{macrocode} -local M = {} +local M = {metadata = metadata} % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Conversion from Markdown to Plain \TeX{}} +%### Conversion from Markdown to Plain \TeX{} % \label{sec:luaconversion} -% The Lua interface exposes the \luamdef{new}\t`(options)` method. This +% The Lua interface exposes the \luamdef{new}`(options)` method. This % method creates converter functions that perform the conversion from markdown -% to plain \TeX{} according to the table \t`options` that contains options +% to plain \TeX{} according to the table `options` that contains options % recognized by the Lua interface. (see Section \ref{sec:luaoptions}). The -% \t`options` parameter is optional; when unspecified, the behaviour will be -% the same as if \t`options` were an empty table. +% `options` parameter is optional; when unspecified, the behaviour will be +% the same as if `options` were an empty table. % -% The following example Lua code converts the markdown string \t`_Hello -% world!_` to a \TeX{} output using the default options and prints the \TeX{} +% The following example Lua code converts the markdown string `Hello +% *world*!` to a \TeX{} output using the default options and prints the \TeX{} % output: -% \begin{Verbatim} +% ``` lua % local md = require("markdown") % local convert = md.new() -% print(convert("_Hello world!_")) -% \end{Verbatim} +% print(convert("Hello *world*!")) +% ``````` % -% \subsubsection{Options}\label{sec:luaoptions} +% \end{markdown} +% \iffalse +%</lua> +%<*manual> + +### Interfaces + +The Lua part of the package exposes two interfaces – the `markdown` Lua module, +and the Lua command-line interface (CLI). + +#### The Lua module + +The `markdown` Lua module exposes the `new(options)` method, which creates a +converter function from markdown to TeX. The properties of the converter +function are specified by the Lua table `options`. The parameter is optional; +when unspecified, the behaviour will be the same as if `options` were an empty +table. + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input example +\bye +``````` +Using a text editor, create a text document named `example.lua` with the +following content: +``` lua +#!/usr/bin/env texlua +local kpse = require("kpse") +kpse.set_program_name("luatex") +local markdown = require("markdown") +local convert_safe = markdown.new() +local convert_unsafe = markdown.new({hybrid = true}) +local input = [[$\sqrt{-1}$ *equals* $i$.]] +print(convert_safe(input) .. " " .. convert_unsafe(input)) +``````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua example.lua > example.tex +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text +“\$\\sqrt{-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” Invoking pdfTeX should have +the same effect: +``` sh +texlua example.lua > example.tex +pdftex document.tex +`````` + +*** + +Rather than use the `texlua` interpreter, we can also access the `markdown` Lua +module directly from our document. Using a text editor, create a text document +named `document.tex` with the following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local convert_safe = markdown.new() + local convert_unsafe = markdown.new({hybrid = true}) + local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]] + tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the text +“\$\\sqrt {-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” In this case, we cannot +use pdfTeX, because pdfTeX does not define the `\directlua` TeX command. + +#### The Lua CLI + +The Lua command-line interface (CLI) accepts the same options as the `markdown` +Lua module, but now the options are specified as command-line parameters. + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input safe\ \input unsafe +\bye +``````` +Using a text editor, create a text document named `example.md` with the +following content: +``` md +$\sqrt{-1}$ *equals* $i$. +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- example.md safe.tex +texlua <CLI␣PATHNAME> hybrid=true -- example.md unsafe.tex +luatex document.tex +`````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the text +“\$\\sqrt{-1}\$ *equals* \$i\$. √-̅1̅ *equals* $i$.” Invoking pdfTeX should have +the same effect: +``` sh +texlua <CLI␣PATHNAME> -- example.md safe.tex +texlua <CLI␣PATHNAME> hybrid=true -- example.md unsafe.tex +pdftex document.tex +`````` + +%</manual> +%<*lua> +% \fi +% \begin{markdown} +% +%### Options +% \label{sec:luaoptions} % The Lua interface recognizes the following options. When unspecified, the % value of a key is taken from the \luamdef{defaultOptions} table. +% +% \end{markdown} +% \iffalse +%</lua> +%<*manual> + +### Options + +This section will cover the options recognized by the Lua interface. The +interfaces of the plain TeX, LaTeX, and ConTeXt macro packages recognize these +options as well, in addition to their own options. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} local defaultOptions = {} % \end{macrocode} -% \pagebreak -% \paragraph{File and Directory Names} -% \begin{optionlist} -% \Valitem[.]{cacheDir}{path} -% A path to the directory containing auxiliary cache files. It is -% considered sane to set the path to a subdirectory of \t`outputDir`. -% If the last segment of the path does not exist, it will be created by the -% plain \TeX, \LaTeX, and \Hologo{ConTeXt} implementations. The Lua -% implementation expects that the entire path already exists. -% -% When iteratively writing and typesetting a markdown document, the cache -% files are going to accumulate over time. You are advised to clean the -% cache directory every now and then, or to set it to a temporary filesystem -% (such as \t`/tmp` on \acro{un*x} systems), which gets periodically -% emptied. +% \begingroup +% \markdownSetup{ +% renderers = { +% dlBegin = {\begin{optionlist}}, +% dlItem = { +% #1 +% \begingroup +% \markdownSetup{ +% renderers = { +% dlBegin = { +% \begingroup +% \markdownSetup{ +% renderers = { +% dlItem = {\item[####1]}, +% dlItemEnd = {}}} +% \begin{valuelist}}, +% dlEnd = { +% \end{valuelist} +% \endgroup}}}}, +% dlItemEnd = {\endgroup}, +% dlEnd = {\end{optionlist}}}} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> +% \fi +% \begin{markdown} + +#### File and Directory Names + +% \end{markdown} +% \par +% \iffalse + +##### Option `cacheDir` + +`cacheDir` (default value: `"."`) + +% \fi +% \begin{markdown} +% +% \Valitem[.]{cacheDir}{path} +% +: A path to the directory containing auxiliary cache files. If the last + segment of the path does not exist, it will be created by the Lua + command-line and plain TeX implementations. The Lua implementation expects + that the entire path already exists. + + When iteratively writing and typesetting a markdown document, the cache + files are going to accumulate over time. You are advised to clean the + cache directory every now and then, or to set it to a temporary filesystem + (such as `/tmp` on UN*X systems), which gets periodically emptied. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\directlua{ + local markdown = require("markdown") + local convert = markdown.new({cacheDir = "cache"}) + local input = "Hello *world*!" + tex.sprint(convert(input)) } +\bye +``````` +Create an empty directory named `cache` next to our text document. Then, invoke +LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” Several cache files of the Markdown package will also be +produced in the `cache` directory as we requested using the `cacheDir` option. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input hello +\bye +``````` +Using a text editor, create a text document named `hello.md` with the +following content: +``` md +Hello *world*! +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> cacheDir=cache -- hello.md hello.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the text +“Hello *world*!” A directory named `cache` containing several cache files of +the Markdown package will also be produced as we requested using the `cacheDir` +option. + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownOptionCacheDir{cache} +\markdownBegin +Hello *world*! +\markdownEnd +\bye +``````` +Next, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” A directory named `cache` containing several cache files of the +Markdown package will also be produced as we requested using the `cacheDir` +option. + +###### LaTeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[cacheDir=cache]{markdown} +\begin{document} +\begin{markdown} +Hello *world*! +\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 text “Hello +*world*!” A directory named `cache` containing several cache files of the +Markdown package will also be produced as we requested using the `cacheDir` +option. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionCacheDir{cache} +\starttext +\startmarkdown +Hello *world*! +\stopmarkdown +\stoptext +``````` +Next, invoke LuaTeX from the terminal: +``` sh +context document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the text “Hello +*world*!” A directory named `cache` containing several cache files of the +Markdown package will also be produced as we requested using the `cacheDir` +option. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.cacheDir = "." % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> +% \fi +% \begin{markdown} + +#### Parser Options + +% \end{markdown} +% \par +% \iffalse + +##### Option `blankBeforeBlockquote` + +`blankBeforeBlockquote` (default value: `false`) + +% \fi +% \begin{markdown} +% \Optitem[false]{blankBeforeBlockquote}{\opt{true}, \opt{false}} % -% \Valitem[.]{outputDir}{path} -% A path to the directory containing output files. The path must be set -% to the same value as the \t`-output-directory` option of your \TeX\ -% engine for the package to function correctly. -% \begin{macrocode} -defaultOptions.outputDir = "." -% \end{macrocode} -% \end{optionlist} -% \paragraph{Parser Options} -% \begin{optionlist} -% \Optitem[false]{blankBeforeBlockquote}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Require a blank line between a paragraph and the following -% blockquote. -% \item[false] Do not require a blank line between a paragraph and the -% following blockquote. -% \end{valuelist} +: true + + : Require a blank line between a paragraph and the following blockquote. + + false + + : Do not require a blank line between a paragraph and the following + blockquote. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local newline = [[^^J^^J]] + local convert, input + + convert = markdown.new() + input = "A paragraph." .. newline .. + "> A quote." .. newline + tex.sprint(convert(input)) + + convert = markdown.new({blankBeforeBlockquote = true}) + input = "A paragraph." .. newline .. + "> Not a quote." .. newline + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> > A quote. +> +> A paragraph > Not a quote. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +A paragraph. +> A quote? +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> blankBeforeBlockquote=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> > A quote? +> +> A paragraph. > A quote? + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown + +\markdownBegin +A paragraph. +> A quote. +\markdownEnd + +\def\markdownOptionBlankBeforeBlockquote{true} +\markdownBegin +A paragraph. +> Not a quote. +\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: + +> A paragraph. +> +> > A quote. +> +> A paragraph > Not a quote. + +###### 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} +A paragraph. +> A quote. +\end{markdown} + +\begin{markdown*}{blankBeforeBlockquote} +A paragraph. +> Not a quote. +\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 quote. +> +> A paragraph > Not a quote. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +A paragraph. +> A quote. +\stopmarkdown + +\def\markdownOptionBlankBeforeBlockquote{true} +\startmarkdown +A paragraph. +> Not a quote. +\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: + +> A paragraph. +> +> > A quote. +> +> A paragraph > Not a quote. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.blankBeforeBlockquote = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `blankBeforeCodeFence` + +`blankBeforeCodeFence` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{blankBeforeCodeFence}{\opt{true}, \opt{false}} % -% \Optitem[false]{blankBeforeCodeFence}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Require a blank line between a paragraph and the following -% fenced code block. -% \item[false] Do not require a blank line between a paragraph and the -% following fenced code block. -% \end{valuelist} +: true + + : Require a blank line between a paragraph and the following fenced code + block. + + false + + : Do not require a blank line between a paragraph and the following + fenced code block. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local newline = [[^^J^^J]] + local convert, input + + convert = markdown.new({fencedCode = true}) + input = "A paragraph." .. newline .. + "```" .. newline .. + "A code fence." .. newline .. + "```" .. newline + tex.sprint(convert(input)) + + convert = markdown.new({ + fencedCode = true, blankBeforeCodeFence = true}) + input = "A paragraph." .. newline .. + "```" .. newline .. + "Not a code fence." .. newline .. + "```" .. newline + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> ``` +> A code fence. +> ``` +> +> A paragraph. ``` Not a code fence. ``` + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +```` md +A paragraph. +``` +A code fence? +``` +``````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> fencedCode=true -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> fencedCode=true blankBeforeCodeFence=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> ``` +> A code fence? +> ``` +> +> A paragraph. ``` A code fence? ``` + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\input markdown +\def\markdownOptionFencedCode{true} + +\markdownBegin +A paragraph. +``` +A code fence. +``` +\markdownEnd + +\def\markdownOptionBlankBeforeCodeFence{true} +\markdownBegin +A paragraph. +``` +Not a code fence. +``` +\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: + +> A paragraph. +> +> ``` +> A code fence. +> ``` +> +> A paragraph. ``` Not a code fence. ``` + +###### LaTeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\documentclass{article} +\usepackage[fencedCode]{markdown} +\begin{document} + +\begin{markdown} +A paragraph. +``` +A code fence. +``` +\end{markdown} + +\begin{markdown*}{blankBeforeCodeFence} +A paragraph. +``` +Not a code fence. +``` +\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 code fence. +> ``` +> +> A paragraph. ``` Not a code fence. ``` + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +```` tex +\usemodule[t][markdown] +\def\markdownOptionFencedCode{true} +\starttext + +\startmarkdown +A paragraph. +``` +A code fence. +``` +\stopmarkdown + +\def\markdownOptionBlankBeforeCodeFence{true} +\startmarkdown +A paragraph. +``` +Not a code fence. +``` +\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: + +> A paragraph. +> +> ``` +> A code fence. +> ``` +> +> A paragraph. ``` Not a code fence. ``` + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.blankBeforeCodeFence = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `blankBeforeHeading` + +`blankBeforeHeading` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{blankBeforeHeading}{\opt{true}, \opt{false}} % -% \Optitem[false]{blankBeforeHeading}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Require a blank line between a paragraph and the following -% header. -% \item[false] Do not require a blank line between a paragraph and the -% following header. -% \end{valuelist} +: true + + : Require a blank line between a paragraph and the following header. + + false + + : Do not require a blank line between a paragraph and the following + header. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\def\markdownRendererHeadingOne#1{{\bf #1}\par} +\directlua{ + local markdown = require("markdown") + local newline = [[^^J^^J]] + local convert, input + + convert = markdown.new() + input = "A paragraph." .. newline .. + "A heading." .. newline .. + "==========" .. newline + tex.sprint(convert(input)) + + convert = markdown.new({blankBeforeHeading = true}) + input = "A paragraph." .. newline .. + "Not a heading." .. newline .. + "==============" .. newline + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> A heading. +> ========== +> +> A paragraph. Not a heading. ============== + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +A paragraph. +A heading? +========== +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> blankBeforeHeading=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> A paragraph. +> +> A heading? +> ========== +> +> A paragraph. A heading? ========== + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown + +\markdownBegin +A paragraph. +A heading. +========== +\markdownEnd + +\def\markdownOptionBlankBeforeHeading{true} +\markdownBegin +A paragraph. +Not a heading. +============== +\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: + +> A paragraph. +> +> A heading. +> ========== +> +> A paragraph. Not a heading. ============== + +###### 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} +A paragraph. +A heading. +========== +\end{markdown} + +\begin{markdown*}{blankBeforeHeading} +A paragraph. +Not a heading. +============== +\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 heading. +> ========== +> +> A paragraph. Not a heading. ============== + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +A paragraph. +A heading. +========== +\stopmarkdown + +\def\markdownOptionBlankBeforeHeading{true} +\startmarkdown +A paragraph. +Not a heading. +============== +\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: + +> A paragraph. +> +> A heading. +> ========== +> +> A paragraph. Not a heading. ============== + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.blankBeforeHeading = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `breakableBlockquotes` + +`breakableBlockquotes` (default value: `false`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{breakableBlockquotes}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] A blank line separates block quotes. -% \item[false] Blank lines in the middle of a block quote are ignored. -% \end{valuelist} +% \Optitem[false]{breakableBlockquotes}{\opt{true}, \opt{false}} +% +: true + + : A blank line separates block quotes. + + false + + : Blank lines in the middle of a block quote are ignored. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\def\markdownRendererHeadingOne#1{{\bf #1}\par} +\directlua{ + local markdown = require("markdown") + local newline = [[^^J^^J]] + local convert, input + + convert = markdown.new() + input = "> A single" .. newline .. newline .. + "> block quote." .. newline + tex.sprint(convert(input)) + + convert = markdown.new({breakableBlockquotes = true}) + input = "> A block quote." .. newline .. newline .. + "> Another block quote." .. newline + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> > A single block quote. +> +> > A block quote. +> +> > Another block quote. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +> A single block quote + +> or two block quotes? +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> breakableBlockquotes=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> > A single block quote or two block quotes? +> +> > A single block quote +> +> > or two block quotes? + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown + +\markdownBegin +> A single + +> block quote. +\markdownEnd + +\def\markdownOptionBreakableBlockquotes{true} +\markdownBegin +> A block quote. + +> Another block quote. +\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: + +> > A single block quote. +> +> > A block quote. +> +> > Another block quote. + +###### 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} +> A single + +> block quote. +\end{markdown} + +\begin{markdown*}{breakableBlockquotes} +> A block quote. + +> Another block quote. +\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 single block quote. +> +> > A block quote. +> +> > Another block quote. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +> A single + +> block quote. +\stopmarkdown + +\def\markdownOptionBreakableBlockquotes{true} +\startmarkdown +> A block quote. + +> Another block quote. +\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: + +> > A single block quote. +> +> > A block quote. +> +> > Another block quote. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.breakableBlockquotes = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `citationNbsps` + +`citationNbsps` (default value: `true`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}} % -% \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Replace regular spaces with non-breakable spaces inside the -% prenotes and postnotes of citations produced via the pandoc citation -% syntax extension. -% \item[false] Do not replace regular spaces with non-breakable spaces -% inside the prenotes and postnotes of citations produced via the pandoc -% citation syntax extension. -% \end{valuelist} +: true + + : Replace regular spaces with non-breakable spaces inside the prenotes + and postnotes of citations produced via the pandoc citation syntax + extension. + + false + + : Do not replace regular spaces with non-breakable spaces inside the + prenotes and postnotes of citations produced via the pandoc citation + syntax extension. + +% \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]{markdown} +\begin{document} + +\begin{markdown} +The TeXbook [@knuth:tex, p. 123 and 130] is good. +\end{markdown} + +\begin{markdown*}{citationNbsps = false} +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, where the middot (`·`) denotes a non-breakable space: + +> The TeXbook [1, p.·123·and·130] is good. +> +> 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> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.citationNbsps = true % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `citations` + +`citations` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{citations}{\opt{true}, \opt{false}} % -% \Optitem[false]{citations}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the pandoc citation syntax extension: -% \begin{Verbatim} -% Here is a simple parenthetical citation [@doe99] and here -% is a string of several [see @doe99, pp. 33-35; also -% @smith04, chap. 1]. -% -% A parenthetical citation can have a [prenote @doe99] and -% a [@smith04 postnote]. The name of the author can be -% suppressed by inserting a dash before the name of an -% author as follows [-@smith04]. -% -% Here is a simple text citation @doe99 and here is -% a string of several @doe99 [pp. 33-35; also @smith04, -% chap. 1]. Here is one with the name of the author -% suppressed -@doe99. -% \end{Verbatim} -% \item[false] Disable the pandoc citation syntax extension. -% \end{valuelist} +: true + + : Enable the pandoc citation syntax extension: + + ``` md + Here is a simple parenthetical citation [@doe99] and here + is a string of several [see @doe99, pp. 33-35; also + @smith04, chap. 1]. + + A parenthetical citation can have a [prenote @doe99] and + a [@smith04 postnote]. The name of the author can be + suppressed by inserting a dash before the name of an + author as follows [-@smith04]. + + Here is a simple text citation @doe99 and here is + a string of several @doe99 [pp. 33-35; also @smith04, + chap. 1]. Here is one with the name of the author + suppressed -@doe99. + `````` + +: false + + : Disable the pandoc citation syntax extension. + +% \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[backend=biber]{biblatex} +\addbibresource{document.bib} +\usepackage[citations]{markdown} +\begin{document} + +\begin{markdown} +The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex. +\end{markdown} + +\printbibliography +\end{document} +``````` +Next, invoke LuaTeX and Biber from the terminal: +``` sh +lualatex document.tex +biber document.bcf +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] was written by Knuth [1]. +> +> ### References +> [1] Donald Ervin Knuth. _The TeXbook, volume A of Computers and typesetting._ +> Addison-Wesley, 1984. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.citations = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `codeSpans` + +`codeSpans` (default value: `true`) + +% \fi +% \begin{markdown} +% +% \Optitem[true]{codeSpans}{\opt{true}, \opt{false}} % -% \Optitem[true]{codeSpans}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the code span syntax: -% \begin{Verbatim} -% Use the `printf()` function. -% ``There is a literal backtick (`) here.`` -% \end{Verbatim} -% \item[false] Disable the code span syntax. This allows you to easily -% use the quotation mark ligatures in texts that do not contain code -% spans: -% \begin{Verbatim} -% ``This is a quote.'' -% \end{Verbatim} -% \end{valuelist} +: true + + : Enable the code span syntax: + + ~~~ md + Use the `printf()` function. + ``There is a literal backtick (`) here.`` + ~~~ + +: false + + : Disable the code span syntax. This allows you to easily + use the quotation mark ligatures in texts that do not contain code + spans: + + ~~~ + ``This is a quote.'' + ~~~~~~ + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local convert = markdown.new() + local input = + "``This is a code span.'' " .. + "``This is no longer a code span.''" + tex.sprint(convert(input)) } +\par +\directlua{ + local markdown = require("markdown") + local convert = markdown.new({codeSpans = false}) + local input = + "``This is a quote.'' " .. + "``This is another quote.''" + tex.sprint(convert(input)) } +\bye +``````` +Then, 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 code span.'' ``This is no longer a code span.'' +> +> “This is a quote.” “This is another quote.” + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\par +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +``Is this a code span?'' ``Or a quote?'' +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> codeSpans=false -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> “Is this a code span?” “Or a quote?” +> +> ``Is this a code span?'' ``Or a quote?'' + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown + +\markdownBegin +``This is a code span.'' +``This is no longer a code span.'' +\markdownEnd + +\def\markdownOptionCodeSpans{false} +\markdownBegin +``This is a quote.'' +``This is another quote.'' +\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 code span.'' ``This is no longer a code span.'' +> +> “This is a quote.” “This is another quote.” + +###### 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} +``This is a code span.'' +``This is no longer a code span.'' +\end{markdown} + +\begin{markdown*}{codeSpans=false} +``This is a quote.'' +``This is another quote.'' +\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 code span.'' ``This is no longer a code span.'' +> +> “This is a quote.” “This is another quote.” + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +``This is a code span.'' +``This is no longer a code span.'' +\stopmarkdown + +\def\markdownOptionCodeSpans{false} +\startmarkdown +``This is a quote.'' +``This is another quote.'' +\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 code span.'' ``This is no longer a code span.'' +> +> “This is a quote.” “This is another quote.” + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.codeSpans = true % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `contentBlocks` + +`contentBlocks` (default value: `false`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{contentBlocks}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the iA\,Writer content blocks syntax -% extension~\cite{sotkov17}: -% \begin{Verbatim} -% http://example.com/minard.jpg (Napoleon’s disastrous -% Russian campaign of 1812) -% /Flowchart.png "Engineering Flowchart" -% /Savings Account.csv 'Recent Transactions' -% /Example.swift -% /Lorem Ipsum.txt -% \end{Verbatim} -% \item[false] Disable the iA\,Writer content blocks syntax extension. -% \end{valuelist} +% \Optitem[false]{contentBlocks}{\opt{true}, \opt{false}} +% +: true + + : Enable the +% iA\,Writer content blocks syntax extension~[@sotkov17]: +% \iffalse + iA Writer content blocks syntax extension: +% \fi + + ``` md + http://example.com/minard.jpg (Napoleon's + disastrous Russian campaign of 1812) + /Flowchart.png "Engineering Flowchart" + /Savings Account.csv 'Recent Transactions' + /Example.swift + /Lorem Ipsum.txt + `````` + +: false + + : Disable the +% iA\,Writer content blocks syntax extension. +% \iffalse + iA Writer content blocks syntax extension. +% \fi + +% \end{markdown} +% \iffalse + +###### LaTeX example {.unnumbered} + +Using a text editor, create a text document named `table.csv` with the +following content: +``` csv +Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847 +``````` +Create also a text document named `markdown-languages.json` with the following +content: +``` js +{ + "tex": "LaTeX" +} +`````` +Create also a text document named `code.tex` with the following content: +``` tex +This is an example code listing in \LaTeX. +``````` +Create also a text document named `part.md` with the following content: +``` md +This is a *transcluded markdown document*. +`````` +Create also a text document named `document.tex` with the following content: +``` tex +\documentclass{article} +\usepackage{minted} +\usepackage[contentBlocks]{markdown} +\begin{document} +\begin{markdown} +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +\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: + +> | Name | Surname | Born | +> | ------ | ---------| ---- | +> | Albert | Einstein | 1879 | +> | Marie | Curie | 1867 | +> | Thomas | Edison | 1847 | +> +> Table 1: An example table +> +> ``` tex +> This is an example code listing in \LaTeX. +> ``````` +> +> This is a *transcluded markdown document*. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `table.csv` with the +following content: +``` csv +Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847 +``````` +Create also a text document named `markdown-languages.json` with the following +content: +``` js +{ + "tex": "ConTeXt" +} +`````` +Create also a text document named `code.tex` with the following content: +``` tex +This is an example code listing in \ConTeXt. +``````` +Create also a text document named `part.md` with the following content: +``` md +This is a *transcluded markdown document*. +`````` +Create also a text document named `document.tex` with the following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionContentBlocks{true} +\definetyping [ConTeXt] +\setuptyping [ConTeXt] [option=TEX] +\starttext +\startmarkdown +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +\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: + +> | Name | Surname | Born | +> | ------ | ---------| ---- | +> | Albert | Einstein | 1879 | +> | Marie | Curie | 1867 | +> | Thomas | Edison | 1847 | +> +> Table 1: An example table +> +> ``` tex +> This is an example code listing in \ConTeXt. +> ``````` +> +> This is a *transcluded markdown document*. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.contentBlocks = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `contentBlocksLanguageMap` + +`contentBlocksLanguageMap` (default value: `"markdown-languages.json"`) + +% \fi +% \begin{markdown} +% +% \Valitem[markdown-languages.json]{contentBlocksLanguageMap}{filename} % -% \Valitem[markdown-languages.json]{contentBlocksLanguageMap}{filename} -% The filename of the \acro{json} file that maps filename extensions to -% programming language names in the iA\,Writer content blocks. See -% Section~\ref{sec:texcontentblockrenderers} for more information. +: The filename of the JSON file that maps filename extensions to + programming language names in the iA Writer content blocks. +% See Section~\ref{sec:texcontentblockrenderers} for more information. + +% \end{markdown} +% \iffalse + +###### LaTeX example {.unnumbered} + +Using a text editor, create a text document named `table.csv` with the +following content: +``` csv +Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847 +``````` +Create also a text document named `language-map.json` with the following +content: +``` js +{ + "tex": "LaTeX" +} +`````` +Create also a text document named `code.tex` with the following content: +``` tex +This is an example code listing in \LaTeX. +``````` +Create also a text document named `part.md` with the following content: +``` md +This is a *transcluded markdown document*. +`````` +Create also a text document named `document.tex` with the following content: +``` tex +\documentclass{article} +\usepackage{minted} +\usepackage[contentBlocks]{markdown} +\markdownSetup{ + contentBlocksLanguageMap = {language-map.json}, +} +\begin{document} +\begin{markdown} +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +\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: + +> | Name | Surname | Born | +> | ------ | ---------| ---- | +> | Albert | Einstein | 1879 | +> | Marie | Curie | 1867 | +> | Thomas | Edison | 1847 | +> +> Table 1: An example table +> +> ``` tex +> This is an example code listing in \LaTeX. +> ``````` +> +> This is a *transcluded markdown document*. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `table.csv` with the +following content: +``` csv +Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847 +``````` +Create also a text document named `language-map.json` with the following +content: +``` js +{ + "tex": "ConTeXt" +} +`````` +Create also a text document named `code.tex` with the following content: +``` tex +This is an example code listing in \ConTeXt. +``````` +Create also a text document named `part.md` with the following content: +``` md +This is a *transcluded markdown document*. +`````` +Create also a text document named `document.tex` with the following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionContentBlocks{true} +\def\markdownOptionContentBlocksLanguageMap{language-map.json} +\definetyping [ConTeXt] +\setuptyping [ConTeXt] [option=TEX] +\starttext +\startmarkdown +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +\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: + +> | Name | Surname | Born | +> | ------ | ---------| ---- | +> | Albert | Einstein | 1879 | +> | Marie | Curie | 1867 | +> | Thomas | Edison | 1847 | +> +> Table 1: An example table +> +> ``` tex +> This is an example code listing in \ConTeXt. +> ``````` +> +> This is a *transcluded markdown document*. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.contentBlocksLanguageMap = "markdown-languages.json" % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `definitionLists` + +`definitionLists` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{definitionLists}{\opt{true}, \opt{false}} % -% \Optitem[false]{definitionLists}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the pandoc definition list syntax extension: -% \begin{Verbatim} -% Term 1 -% -% : Definition 1 -% -% Term 2 with *inline markup* -% -% : Definition 2 -% -% { some code, part of Definition 2 } -% -% Third paragraph of definition 2. -% \end{Verbatim} -% \item[false] Disable the pandoc definition list syntax extension. -% \end{valuelist} +: true + + : Enable the pandoc definition list syntax extension: + + ``` md + Term 1 + + : Definition 1 + + Term 2 with *inline markup* + + : Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. + ````` + +: false + + : Disable the pandoc definition list 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[definitionLists]{markdown} +\begin{document} +\begin{markdown} +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. +\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: + +> Term 1 +> +> : Definition 1 +> +> Term 2 with *inline markup* +> +> : Definition 2 +> +> { some code, part of Definition 2 } +> +> Third paragraph of definition 2. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionDefinitionLists{true} +\starttext +\startmarkdown +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. +\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: + +> Term 1 +> +> : Definition 1 +> +> Term 2 with *inline markup* +> +> : Definition 2 +> +> { some code, part of Definition 2 } +> +> Third paragraph of definition 2. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.definitionLists = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `fencedCode` + +`fencedCode` (default value: `false`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{fencedCode}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the commonmark fenced code block extension: -% \begin{Verbatim} -% ~~~ js -% if (a > 3) { -% moveShip(5 * gravity, DOWN); -% } -% ~~~~~~ -% -% ``` html -% <pre> -% <code> -% // Some comments -% line 1 of code -% line 2 of code -% line 3 of code -% </code> -% </pre> -% ``` -% \end{Verbatim} -% \item[false] Disable the commonmark fenced code block extension. -% \end{valuelist} +% \Optitem[false]{fencedCode}{\opt{true}, \opt{false}} +% +: true + + : Enable the commonmark fenced code block extension: + + ~~~~~~~~ md + ~~~ js + if (a > 3) { + moveShip(5 * gravity, DOWN); + } + ~~~~~~ + + ``` html + <pre> + <code> + // Some comments + line 1 of code + line 2 of code + line 3 of code + </code> + </pre> + ``` + ~~~~~~~~~~~ + +: false + + : Disable the commonmark fenced code block 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{minted} +\usepackage[fencedCode]{markdown} +\begin{document} +\begin{markdown} +~~~ js +if (a > 3) { + moveShip(5 * gravity, DOWN); +} +~~~~~~ + + ``` html + <pre> + <code> + // Some comments + line 1 of code + line 2 of code + line 3 of code + </code> + </pre> + ``` +\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: + +> ~~~ js +> if (a > 3) { +> moveShip(5 * gravity, DOWN); +> } +> ~~~~~~ +> +> ``` html +> <pre> +> <code> +> // Some comments +> line 1 of code +> line 2 of code +> line 3 of code +> </code> +> </pre> +> ``` + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionFencedCode{true} +\definetyping [js] +\definetyping [html] +\setuptyping [html] [option=XML] +\starttext +\startmarkdown +~~~ js +if (a > 3) { + moveShip(5 * gravity, DOWN); +} +~~~~~~ + + ``` html + <pre> + <code> + // Some comments + line 1 of code + line 2 of code + line 3 of code + </code> + </pre> + ``` +\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: + +> ~~~ js +> if (a > 3) { +> moveShip(5 * gravity, DOWN); +> } +> ~~~~~~ +> +> ``` html +> <pre> +> <code> +> // Some comments +> line 1 of code +> line 2 of code +> line 3 of code +> </code> +> </pre> +> ``` + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.fencedCode = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `footnotes` + +`footnotes` (default value: `false`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{footnotes}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the pandoc footnote syntax extension: -% \begin{Verbatim} -% Here is a footnote reference,[^1] and another.[^longnote] -% -% [^1]: Here is the footnote. -% -% [^longnote]: Here's one with multiple blocks. -% -% Subsequent paragraphs are indented to show that they -% belong to the previous footnote. -% -% { some.code } -% -% The whole paragraph can be indented, or just the -% first line. In this way, multi-paragraph footnotes -% work like multi-paragraph list items. -% -% This paragraph won't be part of the note, because it -% isn't indented. -% \end{Verbatim} -% \item[false] Disable the pandoc footnote syntax extension. -% \end{valuelist} +% \Optitem[false]{footnotes}{\opt{true}, \opt{false}} +% +: true + + : Enable the pandoc footnote syntax extension: + + ``` md + Here is a footnote reference,[^1] and another.[^longnote] + + [^1]: Here is the footnote. + + [^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they + belong to the previous footnote. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph footnotes + work like multi-paragraph list items. + + This paragraph won't be part of the note, because it + isn't indented. + `````` + +: false + + : Disable the pandoc footnote 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[footnotes]{markdown} +\begin{document} +\begin{markdown} +Here is a footnote reference,[^1] and another.[^longnote] + +[^1]: Here is the footnote. + +[^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they +belong to the previous footnote. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph footnotes + 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 footnote reference,[^1] and another.[^longnote] +> +> [^1]: Here is the footnote. +> +> [^longnote]: Here's one with multiple blocks. +> +> Subsequent paragraphs are indented to show that they +> belong to the previous footnote. +> +> { some.code } +> +> The whole paragraph can be indented, or just the +> first line. In this way, multi-paragraph footnotes +> work like multi-paragraph list items. +> +> This paragraph won't be part of the note, because it +> isn't indented. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionFootnotes{true} +\starttext +\startmarkdown +Here is a footnote reference,[^1] and another.[^longnote] + +[^1]: Here is the footnote. + +[^longnote]: Here's one with multiple blocks. + + Subsequent paragraphs are indented to show that they +belong to the previous footnote. + + { some.code } + + The whole paragraph can be indented, or just the + first line. In this way, multi-paragraph footnotes + 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 footnote reference,[^1] and another.[^longnote] +> +> [^1]: Here is the footnote. +> +> [^longnote]: Here's one with multiple blocks. +> +> Subsequent paragraphs are indented to show that they +> belong to the previous footnote. +> +> { some.code } +> +> The whole paragraph can be indented, or just the +> first line. In this way, multi-paragraph footnotes +> work like multi-paragraph list items. +> +> This paragraph won't be part of the note, because it +> isn't indented. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.footnotes = false % \end{macrocode} -% -% \Optitem[false]{hashEnumerators}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the use of hash symbols (\t`\#`) as ordered item -% list markers: -% \begin{Verbatim} -% #. Bird -% #. McHale -% #. Parish -% \end{Verbatim} -% \item[false] Disable the use of hash symbols (\t`\#`) as ordered item -% list markers. -% \end{valuelist} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `hashEnumerators` + +`hashEnumerators` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{hashEnumerators}{\opt{true}, \opt{false}} +% +: true + + : Enable the use of hash symbols (`#`) as ordered item list + markers: + + ``` md + #. Bird + #. McHale + #. Parish + `````` + +: false + + : Disable the use of hash symbols (`#`) as ordered item list + markers. + +% \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} +#. Bird +#. McHale +#. Parish +\end{markdown} + +\begin{markdown*}{hashEnumerators} +#. Bird +#. McHale +#. Parish +\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: + +> . Bird +> ======== +> . McHale +> ======== +> . Parish +> ======== +> +> #. Bird +> #. McHale +> #. Parish + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +#. Bird +#. McHale +#. Parish +\stopmarkdown + +\def\markdownOptionHashEnumerators{true} +\startmarkdown +#. Bird +#. McHale +#. Parish +\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: + +> . Bird +> ======== +> . McHale +> ======== +> . Parish +> ======== +> +> #. Bird +> #. McHale +> #. Parish + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.hashEnumerators = false % \end{macrocode} -% -% \Optitem[false]{html}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the recognition of \textsc{html} tags, block -% elements, comments, \textsc{html} instructions, and -% entities in the input. Tags, block elements (along with -% contents), \textsc{html} instructions, and comments will -% be ignored and \textsc{html} entities will be replaced -% with the corresponding Unicode codepoints. -% -% \item[false] Disable the recognition of \textsc{html} markup. Any -% \textsc{html} markup in the input will be rendered as -% plain text. -% \end{valuelist} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `html` + +`html` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{html}{\opt{true}, \opt{false}} +% +: true + + : Enable the recognition of HTML tags, block elements, comments, HTML + instructions, and entities in the input. Tags, block elements (along + with contents), HTML instructions, and comments will be ignored and + HTML entities will be replaced with the corresponding Unicode + codepoints. + +: false + + : Disable the recognition of HTML markup. Any HTML markup in the input + will be rendered as plain text. + +% \end{markdown} +% \iffalse + +When the option is enabled, HTML entities are currently incorrectly parsed. +See [the corresponding issue][issue-38] in the package repository. + + [issue-36]: https://github.com/Witiko/markdown/issues/36 + (HTML entities with the `html` Lua option enabled produce a Lua + parser error) + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local convert = markdown.new() + local newline = [[^^J^^J]] + local input = + "<div>*There is no block tag support.*</div>" .. newline .. + "*There is no <inline tag="tag"></inline> support.*" .. newline .. + "_There is no <!-- comment --> support._" .. newline .. + "_There is no <? HTML instruction ?> support._" + tex.sprint(convert(input)) } +\par +\directlua{ + local markdown = require("markdown") + local convert = markdown.new({html = true}) + local input = + "<div>*There is block tag support.*</div>" .. newline .. + "*There is <inline tag="tag"></inline> support.*" .. newline .. + "_There is <!-- comment --> support._" .. newline .. + "_There is <? HTML instruction ?> support._" + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \<div>There is no block tag support.\</div> +> There is no \<inline tag=”tag”>\</inline> support. +> There is no \<!-- comment --> support. +> There is no <? HTML instruction ?> support. +> +> There is support. There is support. There is support. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\par +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` html +<div> +*Is there block tag support?* +</div> +*Is there <inline tag="tag"></inline> support?* +_Is there <!-- comment --> support?_ +_Is there <? HTML instruction ?> support?_ +```````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> html=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \<div>Is there block tag support?\</div> +> Is there \<inline tag=”tag”>\</inline> support? +> Is there \<!-- comment --> support? +> Is there <? HTML instruction ?> support? +> +> Is there support? Is there support? Is there support? + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts + +\markdownBegin +<div> +*There is no block tag support.* +</div> +*There is no <inline tag="tag"></inline> support.* +_There is no <!-- comment --> support._ +_There is no <? HTML instruction ?> support._ +\markdownEnd + +\def\markdownOptionHtml{true} +\markdownBegin +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +\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: + +> \<div>There is no block tag support.\</div> +> There is no \<inline tag=”tag”>\</inline> support. +> There is no \<!-- comment --> support. +> There is no <? HTML instruction ?> support. +> +> There is support. There is support. There is support. + +###### 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} +<div> +*There is no block tag support.* +</div> +*There is no <inline tag="tag"></inline> support.* +_There is no <!-- comment --> support._ +_There is no <? HTML instruction ?> support._ +\end{markdown} + +\begin{markdown*}{html} +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +\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: + +> \<div>There is no block tag support.\</div> +> There is no \<inline tag=”tag”>\</inline> support. +> There is no \<!-- comment --> support. +> There is no <? HTML instruction ?> support. +> +> There is support. There is support. There is support. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +<div> +*There is no block tag support.* +</div> +*There is no <inline tag="tag"></inline> support.* +_There is no <!-- comment --> support._ +_There is no <? HTML instruction ?> support._ +\stopmarkdown + +\def\markdownOptionHtml{true} +\startmarkdown +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +\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: + +> \<div>There is no block tag support.\</div> +> There is no \<inline tag=”tag”>\</inline> support. +> There is no \<!-- comment --> support. +> There is no <? HTML instruction ?> support. +> +> There is support. There is support. There is support. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.html = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `hybrid` + +`hybrid` (default value: `true`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{hybrid}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Disable the escaping of special plain \TeX{} characters, -% which makes it possible to intersperse your markdown markup with -% \TeX{} code. The intended usage is in documents prepared manually by -% a human author. In such documents, it can often be desirable to mix -% \TeX{} and markdown markup freely. +% \Optitem[false]{hybrid}{\opt{true}, \opt{false}} % -% \item[false] Enable the escaping of special plain \TeX{} characters -% outside verbatim environments, so that they are not interpretted by -% \TeX{}. This is encouraged when typesetting automatically generated -% content or markdown documents that were not prepared with this -% package in mind. -% \end{valuelist} +: true + + : Disable the escaping of special plain TeX characters, which makes it + possible to intersperse your markdown markup with TeX code. The + intended usage is in documents prepared manually by a human author. + In such documents, it can often be desirable to mix TeX and markdown + markup freely. + +: false + + : Enable the escaping of special plain TeX characters outside verbatim + environments, so that they are not interpretted by TeX. This is + encouraged when typesetting automatically generated content or + markdown documents that were not prepared with this package in mind. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\directlua{ + local markdown = require("markdown") + local convert_safe = markdown.new() + local convert_unsafe = markdown.new({hybrid = true}) + local input = [[$\noexpand\sqrt{-1}$ *equals* $i$.]] + tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \$\\sqrt {-1}\$ *equals* \$i\$. +> √-̅1̅ *equals* $i$. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\input optionfalse +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +$\sqrt{-1}$ *equals* $i$. +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> hybrid=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> \$\\sqrt {-1}\$ *equals* \$i\$. +> √-̅1̅ *equals* $i$. + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\input lmfonts +\markdownBegin +$\sqrt{-1}$ *equals* $i$. +\markdownEnd +\def\markdownOptionHybrid{true} +\markdownBegin +$\sqrt{-1}$ *equals* $i$. +\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: + +> \$\\sqrt {-1}\$ *equals* \$i\$. +> √-̅1̅ *equals* $i$. + +###### 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} +$\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\$. +> √-̅1̅ *equals* $i$. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext +\startmarkdown +$\sqrt{-1}$ *equals* $i$. +\stopmarkdown +\def\markdownOptionHybrid{true} +\startmarkdown +$\sqrt{-1}$ *equals* $i$. +\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: + +> \$\\sqrt {-1}\$ *equals* \$i\$. +> √-̅1̅ *equals* $i$. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.hybrid = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `inlineFootnotes` + +`inlineFootnotes` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{inlineFootnotes}{\opt{true}, \opt{false}} % -% \Optitem[false]{inlineFootnotes}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Enable the pandoc inline footnote syntax extension: -% \begin{Verbatim} -% Here is an inline note.^[Inlines notes are easier to -% write, since you don't have to pick an identifier and -% move down to type the note.] -% \end{Verbatim} -% \item[false] Disable the pandoc inline footnote syntax extension. -% \end{valuelist} +: true + + : Enable the pandoc inline footnote syntax extension: + + ``` md + Here is an inline note.^[Inlines notes are easier to + write, since you don't have to pick an identifier and + move down to type the note.] + `````` + +: false + + : Disable the pandoc inline footnote 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[footnotes, inlineFootnotes]{markdown} +\begin{document} +\begin{markdown} +Here is an inline note.^[Inlines notes are easier to +write, since you don't have to pick an identifier and +move down to type the note.] +\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 an inline note.^[Inlines notes are easier to +> write, since you don't have to pick an identifier and +> move down to type the note.] + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionFootnotes{true} +\def\markdownOptionInlineFootnotes{true} +\starttext +\startmarkdown +Here is an inline note.^[Inlines notes are easier to +write, since you don't have to pick an identifier and +move down to type the note.] +\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 an inline note.^[Inlines notes are easier to +> write, since you don't have to pick an identifier and +> move down to type the note.] + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.inlineFootnotes = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `preserveTabs` + +`preserveTabs` (default value: `false`) + +% \fi +% \begin{markdown} % -% \Optitem[false]{preserveTabs}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Preserve all tabs in the input. -% \item[false] Convert any tabs in the input to spaces. -% \end{valuelist} +% \Optitem[false]{preserveTabs}{\opt{true}, \opt{false}} +% +: true + + : Preserve all tabs in the input. + +: false + + : Convert any tabs in the input to spaces. + +% \end{markdown} +% \iffalse + +This option is currently non-functional. See [the corresponding +issue][issue-38] in the package repository. + + [issue-38]: https://github.com/Witiko/markdown/issues/38 + (Tabs are stripped even with the `preserveTabs=true` + Lua option enabled) + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.preserveTabs = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `smartEllipses` + +`smartEllipses` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{smartEllipses}{\opt{true}, \opt{false}} % -% \Optitem[false]{smartEllipses}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Convert any ellipses in the input to the -% \m{markdownRendererEllipsis} \TeX{} macro. -% \item[false] Preserve all ellipses in the input. -% \end{valuelist} +: true + + : Convert any ellipses in the input to the +% \m{markdownRendererEllipsis} \TeX{} macro. +% \iffalse + `\markdownRendererEllipsis` TeX macro. +% \fi + +: false + + : Preserve all ellipses in the input. + +% \end{markdown} +% \iffalse + +###### Lua module example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownRendererEllipsis{. . .} +\input lmfonts +\directlua{ + local markdown = require("markdown") + local convert = markdown.new() + input = "These are just three regular dots ..." + tex.sprint(convert(input)) } +\par +\directlua{ + local markdown = require("markdown") + local convert = markdown.new({smartEllipses = true}) + input = "... and this is a victorian ellipsis." + tex.sprint(convert(input)) } +\bye +``````` +Then, invoke LuaTeX from the terminal: +``` sh +luatex document.tex +``````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> These are just three regular dots ... +> +> . . . and this is a victorian ellipsis. + +###### Lua CLI example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownRendererEllipsis{. . .} +\input lmfonts +\input optionfalse +\par +\input optiontrue +\bye +``````` +Using a text editor, create a text document named `content.md` with the +following content: +``` md +Are these just three regular dots, a victorian ellipsis, or ... ? +`````` +Next, invoke LuaTeX from the terminal: +``` sh +texlua <CLI␣PATHNAME> -- content.md optionfalse.tex +texlua <CLI␣PATHNAME> smartEllipses=true -- content.md optiontrue.tex +luatex document.tex +``````` +where `<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\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua` on Windows +systems. Use the command `kpsewhich markdown-cli.lua` to locate the Lua CLI +script file using [Kpathsea][]. + +A PDF document named `document.pdf` should be produced and contain the +following text: + +> Are these just three regular dots, a victorian ellipsis, or ... ? +> +> Are these just three regular dots, a victorian ellipsis, or . . . ? + +###### Plain TeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\input markdown +\def\markdownRendererEllipsis{. . .} + +\markdownBegin +These are just three regular dots ... +\markdownEnd + +\def\markdownOptionSmartEllipses{true} +\markdownBegin +... and this is a victorian ellipsis. +\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: + +> These are just three regular dots ... +> +> . . . and this is a victorian ellipsis. + +###### 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 = { + ellipsis = {. . .} }} +\begin{document} + +\begin{markdown} +These are just three regular dots ... +\end{markdown} + +\begin{markdown*}{smartEllipses} +... and this is a victorian ellipsis. +\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: + +> These are just three regular dots ... +> +> . . . and this is a victorian ellipsis. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownRendererEllipsis{. . .} +\starttext + +\startmarkdown +These are just three regular dots ... +\stopmarkdown + +\def\markdownOptionSmartEllipses{true} +\startmarkdown +... and this is a victorian ellipsis. +\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: + +> These are just three regular dots ... +> +> . . . and this is a victorian ellipsis. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.smartEllipses = false % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `startNumber` + +`startNumber` (default value: `true`) + +% \fi +% \begin{markdown} +% +% \Optitem[true]{startNumber}{\opt{true}, \opt{false}} % -% \Optitem[true]{startNumber}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Make the number in the first item in ordered lists -% significant. The item numbers will be passed to the -% \m{markdownRendererOlItemWithNumber} \TeX{} macro. -% \item[false] Ignore the number in the items of ordered lists. Each -% item will only produce a \m{markdownRendererOlItem} \TeX{} macro. -% \end{valuelist} +: true + + : Make the number in the first item of an ordered lists significant. The + item numbers will be passed to the +% \m{markdownRendererOlItemWithNumber} \TeX{} macro. +% \iffalse + `\markdownRendererOlItemWithNumber` TeX macro. +% \fi + +: false + + : Ignore the numbers in the ordered list items. Each item will only + produce a +% \m{markdownRendererOlItem} \TeX{} macro. +% \iffalse + `\markdownRendererOlItem` TeX macro. +% \fi + +% \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} +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth item +\end{markdown} + +\begin{markdown*}{startNumber=false} +The following list does not respect the numbers specified in the +markup: + +3. third item +4. fourth item +5. fifth item +\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 following list respects the numbers specified in the markup: +> +> 3. third item +> 4. fourth item +> 5. fifth item +> +> The following list does not respect the numbers specified in the markup: +> +> 1. third item +> 2. fourth item +> 3. fifth item + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\starttext + +\startmarkdown +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth item +\stopmarkdown + +\def\markdownOptionStartNumber{false} +\startmarkdown +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth 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: + +> The following list respects the numbers specified in the markup: +> +> 3. third item +> 4. fourth item +> 5. fifth item +> +> The following list does not respect the numbers specified in the markup: +> +> 1. third item +> 2. fourth item +> 3. fifth item + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.startNumber = true % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `tightLists` + +`tightLists` (default value: `true`) + +% \fi +% \begin{markdown} % -% \Optitem[true]{tightLists}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Lists whose bullets do not consist of multiple paragraphs -% will be detected and passed to the -% \m{markdownRendererOlBeginTight}, \m{markdownRendererOlEndTight}, -% \m{markdownRendererUlBeginTight}, \m{markdownRendererUlEndTight}, -% \m{markdownRendererDlBeginTight}, and \m{markdownRendererDlEndTight} -% macros. -% \item[false] Lists whose bullets do not consist of multiple paragraphs -% will be treated the same way as lists that do. -% \end{valuelist} +% \Optitem[true]{tightLists}{\opt{true}, \opt{false}} +% +: true + + : Lists whose bullets do not consist of multiple paragraphs will be + passed to the +% \m{markdownRendererOlBeginTight}, \m{markdownRendererOlEndTight}, +% \m{markdownRendererUlBeginTight}, \m{markdownRendererUlEndTight}, +% \m{markdownRendererDlBeginTight}, and +% \m{markdownRendererDlEndTight} \TeX{} macros. +% \iffalse + `\markdownRendererOlBeginTight`, `\markdownRendererOlEndTight`, + `\markdownRendererUlBeginTight`, `\markdownRendererUlEndTight`, + `\markdownRendererDlBeginTight`, and + `\markdownRendererDlEndTight` TeX macros. +% \fi + +: false + + : Lists whose bullets do not consist of multiple paragraphs will be + treated the same way as lists that do consist of multiple paragraphs. + +% \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} +The following list is tight: + + - first item + - second item + - third item + +The following list is loose: + + - first item + - second item that spans + + multiple paragraphs + - third item +\end{markdown} + +\begin{markdown*}{tightLists=false} +The following list is now also loose: + + - first item + - second item + - third item +\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 following list is tight: +> +> - first item +> - second item +> - third item +> +> The following list is loose: +> +> - first item +> - second item that spans +> +> multiple paragraphs +> - third item +> +> The following list is now also loose: +> +> - first item +> +> - second item +> +> - third item + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.tightLists = true % \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual> + +##### Option `underscores` + +`underscores` (default value: `true`) + +% \fi +% \begin{markdown} % -% \Optitem[true]{underscores}{\opt{true}, \opt{false}} -% \begin{valuelist} -% \item[true] Both underscores and asterisks can be used to denote -% emphasis and strong emphasis: -% \begin{Verbatim} -% *single asterisks* -% _single underscores_ -% **double asterisks** -% __double underscores__ -% \end{Verbatim} -% \item[false] Only asterisks can be used to denote emphasis and strong -% emphasis. This makes it easy to write math with the \t`hybrid` option -% without the need to constantly escape subscripts. -% \end{valuelist} +% \Optitem[true]{underscores}{\opt{true}, \opt{false}} +% +: true + + : Both underscores and asterisks can be used to denote emphasis and + strong emphasis: + + ``` md + *single asterisks* + _single underscores_ + **double asterisks** + __double underscores__ + `````` + +: false + + : Only asterisks can be used to denote emphasis and strong emphasis. + This makes it easy to write math with the \Opt{hybrid} option + without the need to constantly escape subscripts. + +% \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\markdownOptionHybrid{true} + +\markdownBegin +This is _emphasized text_ and this is a math subscript: $m\_n$. +\markdownEnd + +\def\markdownOptionUnderscores{false} +\markdownBegin +This is *emphasized text* and this is a math subscript: $m_n$. +\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 _emphasized text_ and this is a math subscript: *mₙ*. +> +> This is _emphasized text_ and this is a math subscript: *mₙ*. + +###### LaTeX example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\documentclass{article} +\usepackage[hybrid]{markdown} +\begin{document} + +\begin{markdown} +This is _emphasized text_ and this is a math subscript: $m\_n$. +\end{markdown} + +\begin{markdown*}{underscores=false} +This is *emphasized text* and this is a math subscript: $m_n$. +\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 _emphasized text_ and this is a math subscript: *mₙ*. +> +> This is _emphasized text_ and this is a math subscript: *mₙ*. + +###### ConTeXt example {.unnumbered} + +Using a text editor, create a text document named `document.tex` with the +following content: +``` tex +\usemodule[t][markdown] +\def\markdownOptionHybrid{true} +\starttext + +\startmarkdown +This is _emphasized text_ and this is a math subscript: $m\_n$. +\stopmarkdown + +\def\markdownOptionUnderscores{false} +\startmarkdown +This is *emphasized text* and this is a math subscript: $m_n$. +\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 _emphasized text_ and this is a math subscript: *mₙ*. +> +> This is _emphasized text_ and this is a math subscript: *mₙ*. + +%</manual> +%<*lua,lua-cli> +% \fi % \begin{macrocode} defaultOptions.underscores = true % \end{macrocode} -% \end{optionlist} -% +% \endgroup % \iffalse -%</lua> +%</lua,lua-cli> +%<*lua-cli> +% \fi +% \par +% \begin{markdown} +% +%### Command-Line Interface +% \label{sec:lua-cli-interface} +% To provide finer control over the conversion and to simplify debugging, a +% command-line Lua interface for converting a Markdown document to \TeX{} is +% also provided. +% +% \end{markdown} +% \begin{macrocode} + +HELP_STRING = [[ +Usage: texlua ]] .. arg[0] .. [[ [OPTIONS] -- [INPUT_FILE] [OUTPUT_FILE] +where OPTIONS are documented in the Lua interface section of the +technical Markdown package documentation. + +When OUTPUT_FILE is unspecified, the result of the conversion will be +written to the standard output. When INPUT_FILE is also unspecified, the +result of the conversion will be read from the standard input. + +Report bugs to: witiko@mail.muni.cz +Markdown package home page: <https://github.com/witiko/markdown>]] + +VERSION_STRING = [[ +markdown-cli.lua (Markdown) ]] .. metadata.version .. [[ + +Copyright (C) ]] .. table.concat(metadata.copyright, + "\nCopyright (C) ") .. [[ + +License: ]] .. metadata.license + +local function warn(s) + io.stderr:write("Warning: " .. s .. "\n") end + +local function error(s) + io.stderr:write("Error: " .. s .. "\n") + os.exit(1) end + +local process_options = true +local options = {} +local input_filename +local output_filename +for i = 1, #arg do + if process_options then +% \end{macrocode} +% \begin{markdown} +% After the optional `-`{}`-` argument has been specified, the remaining +% arguments are assumed to be input and output filenames. This argument is +% optional, but encouraged, because it helps resolve ambiguities when +% deciding whether an option or a filename has been specified. +% \end{markdown} +% \begin{macrocode} + if arg[i] == "--" then + process_options = false + goto continue +% \end{macrocode} +% \begin{markdown} +% Unless the `-`{}`-` argument has been specified before, an argument +% containing the equals sign (`=`) is assumed to be an option specification in +% a \meta{key}`=`\meta{value} format. The available options are listed in +% Section~\ref{sec:luaoptions}. +% \end{markdown} +% \begin{macrocode} + elseif arg[i]:match("=") then + key, value = arg[i]:match("(.-)=(.*)") +% \end{macrocode} +% \begin{markdown} +% The \luam{defaultOptions} table is consulted to identify whether \meta{value} +% should be parsed as a string or as a boolean. +% \end{markdown} +% \begin{macrocode} + default_type = type(defaultOptions[key]) + if default_type == "boolean" then + options[key] = (value == "true") + else + if default_type ~= "string" then + if default_type == "nil" then + warn('Option "' .. key .. '" not recognized.') + else + warn('Option "' .. key .. '" type not recognized, please file ' .. + 'a report to the package maintainer.') + end + warn('Parsing the ' .. 'value "' .. value ..'" of option "' .. + key .. '" as a string.') + end + options[key] = value + end + goto continue +% \end{macrocode} +% \begin{markdown} +% Unless the `-`{}`-` argument has been specified before, an argument +% `-`{}`-help`, or `-h` causes a brief documentation for how to invoke the +% program to be printed to the standard output. +% \end{markdown} +% \begin{macrocode} + elseif arg[i] == "--help" or arg[i] == "-h" then + print(HELP_STRING) + os.exit() +% \end{macrocode} +% \begin{markdown} +% Unless the `-`{}`-` argument has been specified before, an argument +% `-`{}`-version`, or `-v` causes the program to print information about its +% name, version, origin and legal status, all on standard output. +% \end{markdown} +% \begin{macrocode} + elseif arg[i] == "--version" or arg[i] == "-v" then + print(VERSION_STRING) + os.exit() + end + end +% \end{macrocode} +% \begin{markdown} +% The first argument that matches none of the above patters is assumed to be +% the input filename. The input filename should correspond to the Markdown +% document that is going to be converted to a \TeX{} document. +% \end{markdown} +% \begin{macrocode} + if input_filename == nil then + input_filename = arg[i] +% \end{macrocode} +% \begin{markdown} +% The first argument that matches none of the above patters is assumed to be +% the output filename. The output filename should correspond to the \TeX{} +% document that will result from the conversion. +% \end{markdown} +% \begin{macrocode} + elseif output_filename == nil then + output_filename = arg[i] + else + error('Unexpected argument: "' .. arg[i] .. '".') + end + ::continue:: +end +% \end{macrocode} +% \par +% \begin{markdown} +% +% The command-line Lua interface is implemented by the `markdown-cli.lua` +% file that can be invoked from the command line as follows: +% ``` sh +% texlua /path/to/markdown-cli.lua cacheDir=. -- hello.md hello.tex +% `````` +% \noindent to convert the Markdown document `hello.md` to a \TeX{} document +% `hello.tex`. After the Markdown package for our \TeX{} format has been +% loaded, the converted document can be typeset as follows: +% ``` tex +% \input hello +% ``````` +% +% This shows another advantage of using the command-line interface compared to +% using a higher-level \TeX{} interface -- it is unnecessary to provide shell +% access for the \TeX{} engine. +% +% \end{markdown} +% \iffalse +%</lua-cli> %<*tex> -% \fi\subsection{Plain \TeX{} Interface}\label{sec:texinterface} -% The plain \TeX{} interface provides macros for the typesetting of markdown input -% from within plain \TeX{}, for setting the Lua interface options (see Section -% \ref{sec:luaoptions}) used during the conversion from markdown to plain -% \TeX{}, and for changing the way markdown the tokens are rendered. +% \fi +% \par +% \begin{markdown} +% +% Plain \TeX{} Interface +%----------------------- +% \label{sec:texinterface} +% +% \iffalse +%</tex> +%<*manual> + +Plain TeX +--------- + +The plain TeX macro package provides TeX commands for typesetting markdown +documents that invoke the Lua parser in the background. Beside TeX commands +that correspond to the Lua options, the macro package also provides commands +corresponding to additional plain TeX-specific options, and so-called *token +renderer* commands that define how the individual markdown elements will be +typeset. + +### Interfaces + +<!-- TODO --> + +%</manual> +%<*tex> +% \fi +% +% The plain \TeX{} interface provides macros for the typesetting of markdown +% input from within plain \TeX{}, for setting the Lua interface options (see +% Section \ref{sec:luaoptions}) used during the conversion from markdown to +% plain \TeX{}, and for changing the way markdown the tokens are rendered. +% +% \end{markdown} % \begin{macrocode} -\def\markdownLastModified{2018/01/08}% -\def\markdownVersion{2.5.5}% +\def\markdownLastModified{2018/04/08}% +\def\markdownVersion{2.5.6}% % \end{macrocode} +% \par +% \begin{markdown} % -% The plain \TeX{} interface is implemented by the \t`markdown.tex` file that -% can be loaded as follows: -% \begin{Verbatim} +% The plain \TeX{} interface is implemented by the `markdown.tex` file that can +% be loaded as follows: +% ``` tex % \input markdown -% \end{Verbatim} -% It is expected that the special plain \TeX{} characters have the expected -% category codes, when \m{input}ting the file. +% ``````` +% \noindent It is expected that the special plain \TeX{} characters have the +% expected category codes, when \m{input}ting the file. % -% \subsubsection{Typesetting Markdown}\label{sec:textypesetting} +%### Typesetting Markdown +% \label{sec:textypesetting} % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, and % \mdef{markdownInput} macros. % % The \m{markdownBegin} macro marks the beginning of a markdown document % fragment and the \m{markdownEnd} macro marks its end. +% +% \end{markdown} % \begin{macrocode} \let\markdownBegin\relax \let\markdownEnd\relax % \end{macrocode} +% \par +% \begin{markdown} +% % You may prepend your own code to the \m{markdownBegin} macro and redefine the % \m{markdownEnd} macro to produce special effects before and after the % markdown block. @@ -783,14 +4963,15 @@ defaultOptions.underscores = true % % 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{} (see -% \cite[p.~46]{knuth86}). As a corrolary, the \m{markdownBegin} macro also +% spaces are removed before the lines enter the input buffer of +% \TeX{}~[@knuth86, p. 46]. As a corrolary, the \m{markdownBegin} macro also % ignores them. % % The \m{markdownBegin} and \m{markdownEnd} macros will also consume the rest % of the lines at which they appear. In the following example plain \TeX{} -% code, the characters \t`c`, \t`e`, and \t`f` will not appear in the output. -% \begin{Verbatim} +% code, the characters `c`, `e`, and `f` will not appear in the output. +% +% ``` tex % \input markdown % a % b \markdownBegin c @@ -798,114 +4979,166 @@ defaultOptions.underscores = true % e \markdownEnd f % g % \bye -% \end{Verbatim} +% ``````` % % Note that you may also not nest the \m{markdownBegin} and \m{markdownEnd} % macros. % % The following example plain \TeX{} code showcases the usage of the % \m{markdownBegin} and \m{markdownEnd} macros: -% \begin{Verbatim} +% +% ``` tex % \input markdown % \markdownBegin % _Hello_ **world** ... % \markdownEnd % \bye -% \end{Verbatim} +% ``````` % % The \m{markdownInput} macro accepts a single parameter containing the % filename of a markdown document and expands to the result of the conversion % of the input markdown document to plain \TeX{}. +% +% \end{markdown} % \begin{macrocode} \let\markdownInput\relax % \end{macrocode} +% \par +% \begin{markdown} +% % This macro is not subject to the abovelisted limitations of the % \m{markdownBegin} and \m{markdownEnd} macros. % % The following example plain \TeX{} code showcases the usage of the % \m{markdownInput} macro: -% \begin{Verbatim} +% +% ``` tex % \input markdown % \markdownInput{hello.md} % \bye -% \end{Verbatim} +% ``````` +% +%### Options +% \label{sec:texoptions} +% +% \iffalse +%</tex> +%<*manual> + +### Options + +<!-- TODO --> + +%</manual> +%<*tex> +% \fi % -% \subsubsection{Options}\label{sec:texoptions} % The plain \TeX{} options are represented by \TeX{} macros. Some of them map -% directly to the options recognized by the Lua interface (see Section -% \ref{sec:luaoptions}), while some of them are specific to the plain \TeX{} -% interface. +% directly to the options recognized by the Lua interface (see +% Section~\ref{sec:luaoptions}), while some of them are specific to the plain +% \TeX{} interface. % -% \paragraph{File and Directory names} +%#### File and Directory names % 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 \m{directlua} primitive. It -% defaults to \m{jobname}\t`.markdown.lua`, where \m{jobname} is the base name +% defaults to \m{jobname}`.markdown.lua`, where \m{jobname} is the base name % of the document being typeset. % -% The expansion of this macro must not contain quotation marks (\t`"`) or -% backslash symbols (\t`\textbackslash`). Mind that \TeX{} engines tend to +% The expansion of this macro must not contain quotation marks (`"`) or +% backslash symbols (`extbackslash`). Mind that \TeX{} engines tend to % put quotation marks around \m{jobname}, when it contains spaces. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionHelperScriptFileName{\jobname.markdown.lua}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownOptionInputTempFileName} macro sets the filename of the % temporary input file that is created during the conversion from markdown to -% plain \TeX{} in \m{markdownMode} other than \t`2`. It defaults to -% \m{jobname}\t`.markdown.out`. The same limitations as in the case of the +% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to +% \m{jobname}`.markdown.out`. The same limitations as in the case of the % \m{markdownOptionHelperScriptFileName} macro apply here. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionInputTempFileName{\jobname.markdown.in}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownOptionOutputTempFileName} macro sets the filename of the % temporary output file that is created during the conversion from markdown to -% plain \TeX{} in \m{markdownMode} other than \t`2`. It defaults to -% \m{jobname}\t`.markdown.out`. The same limitations apply here as in the case +% plain \TeX{} in \m{markdownMode} other than `2`. It defaults to +% \m{jobname}`.markdown.out`. The same limitations apply here as in the case % of the \m{markdownOptionHelperScriptFileName} macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionOutputTempFileName{\jobname.markdown.out}% % \end{macrocode} +% \par +% \begin{markdown} % % 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 \m{markdownMode} other than -% \t`2`. It defaults to \m{jobname}\t`.markdown.err`. The same limitations +% `2`. It defaults to \m{jobname}`.markdown.err`. The same limitations % apply here as in the case of the \m{markdownOptionHelperScriptFileName} % macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionErrorTempFileName{\jobname.markdown.err}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownOptionCacheDir} macro corresponds to the Lua interface -% \Opt{cacheDir} option that sets the name of the directory that will contain -% the produced cache files. The option defaults to \t`_markdown_`\m{jobname}, +% \Opt{cacheDir} option that sets the path to the directory that will contain +% the produced cache files. The option defaults to `_markdown_`\m{jobname}, % which is a similar naming scheme to the one used by the \pkg{minted} \LaTeX{} % package. The same limitations apply here as in the case of the % \m{markdownOptionHelperScriptFileName} macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionCacheDir{\markdownOptionOutputDir/_markdown_\jobname}% % \end{macrocode} +% \par +% \begin{markdown} % -% The \mdef{markdownOptionOutputDir} macro corresponds to the Lua interface -% \Opt{outputDir} option that sets the name of the directory that will contain -% the produced cache files. The option defaults to \t`.`. The same limitations -% apply here as in the case of the \m{markdownOptionHelperScriptFileName} -% macro. +% The \mdef{markdownOptionOutputDir} macro sets the path to the directory that +% will contain the cache files produced by the Lua implementation and also the +% auxiliary files produced by the plain TeX implementation. The option defaults +% to `.`. +% +% The path must be set to the same value as the `-output-directory` option of +% 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 +% \m{markdownOptionHelperScriptFileName} macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownOptionOutputDir{.}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Lua Interface Options} +%#### Lua Interface Options % The following macros map directly to the options recognized by the Lua % interface (see Section \ref{sec:luaoptions}) and are not processed by the % plain \TeX{} implementation, only passed along to Lua. They are undefined, which % makes them fall back to the default values provided by the Lua interface. -% +% % 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 % \m{markdownOptionHelperScriptFileName} macro. +% +% \end{markdown} % \begin{macrocode} \let\markdownOptionBlankBeforeBlockquote\undefined \let\markdownOptionBlankBeforeCodeFence\undefined @@ -927,8 +5160,59 @@ defaultOptions.underscores = true \let\markdownOptionStartNumber\undefined \let\markdownOptionTightLists\undefined % \end{macrocode} +% \par +% \begin{markdown} +% +%#### Miscellaneous options +% The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent +% sign (`%`) at the beginning of a line will be discarded when buffering +% Markdown input (see Section~\ref{sec:buffering}) or not. Notably, this +% enables the use of markdown when writing \TeX{} package documentation using +% the \pkg{Doc} \LaTeX{}~package~[@mittelbach17] or similar. The recognized +% values of the macro are `true` (discard), and `false` (retain). +% +% \end{markdown} +% \begin{macrocode} +\def\markdownOptionStripPercentSigns{false}% +% \end{macrocode} +% \par +% \begin{markdown} +% +% The \mdef{markdownIfOption}`{`\meta{name}`}` macro is provided for testing, +% whether the value of `\markdownOption`\meta{name} is `true` or `false`. +% +% \end{markdown} +% \begin{macrocode} +\def\markdownIfOption#1{% + \def\next##1##2##3##4##5{% + \expandafter\def\expandafter\next\expandafter{% + \csname iffalse\endcsname}% + \if##1t\if##2r\if##3u\if##4e + \expandafter\def\expandafter\next\expandafter{% + \csname iftrue\endcsname}% + \fi\fi\fi\fi + \next}% + \expandafter\expandafter\expandafter\next + \csname markdownOption#1\endcsname\relax\relax\relax\relax\relax} +% \end{macrocode} +% \par +% \begin{markdown} +% +%### Token Renderers +% \label{sec:texrenderersuser} +% +% \iffalse +%</tex> +%<*manual> + +### Token renderers + +<!-- TODO --> + +%</manual> +%<*tex> +% \fi % -% \subsubsection{Token Renderers}\label{sec:texrenderersuser} % The following \TeX{} macros may occur inside the output of the % converter functions exposed by the Lua interface (see Section % \ref{sec:luaconversion}) and represent the parsed markdown tokens. These @@ -936,43 +5220,61 @@ defaultOptions.underscores = true % document. By default, they point to the corresponding prototypes (see Section % \ref{sec:texrendererprototypes}). % -% \paragraph{Interblock Separator Renderer} +%#### Interblock Separator Renderer % The \mdef{markdownRendererInterblockSeparator} macro represents a separator % between two markdown block elements. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererInterblockSeparator{% \markdownRendererInterblockSeparatorPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Line Break Renderer} +%#### Line Break Renderer % The \mdef{markdownRendererLineBreak} macro represents a forced line break. % The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererLineBreak{% \markdownRendererLineBreakPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Ellipsis Renderer} +%#### 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 \t`true`. The macro receives no arguments. +% \Opt{smartEllipses} option is `true`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererEllipsis{% \markdownRendererEllipsisPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Non-breaking Space Renderer} +%#### Non-breaking Space Renderer % The \mdef{markdownRendererNbsp} macro represents a non-breaking space. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererNbsp{% \markdownRendererNbspPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Special Character Renderers} +%#### Special Character Renderers % The following macros replace any special plain \TeX{} characters (including -% the active pipe character (\t`|`) of \Hologo{ConTeXt}) in the input text. +% the active pipe character (`|`) of \Hologo{ConTeXt}) in the input text. % These macros will only be produced, when the \Opt{hybrid} option is -% \t`false`. +% `false`. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererLeftBrace{% \markdownRendererLeftBracePrototype}% @@ -997,402 +5299,579 @@ defaultOptions.underscores = true \def\markdownRendererPipe{% \markdownRendererPipePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Code Span Renderer} +%#### Code Span Renderer % The \mdef{markdownRendererCodeSpan} macro represents inlined code span in the % input text. It receives a single argument that corresponds to the inlined % code span. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererCodeSpan{% \markdownRendererCodeSpanPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Link Renderer} +%#### 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} % \begin{macrocode} \def\markdownRendererLink{% \markdownRendererLinkPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Image Renderer} +%#### 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} % \begin{macrocode} \def\markdownRendererImage{% \markdownRendererImagePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Content Block Renderers}\label{sec:texcontentblockrenderers} +%#### Content Block Renderers +% \label{sec: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} % \begin{macrocode} \def\markdownRendererContentBlock{% \markdownRendererContentBlockPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererContentBlockOnlineImage} macro represents an % iA\,Writer online image content block. The macro receives the same arguments % as \m{markdownRendererContentBlock}. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererContentBlockOnlineImage{% \markdownRendererContentBlockOnlineImagePrototype}% % \end{macrocode} +% \par +% \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 \t`markdown-languages.json` file found +% by its filename extension $s$. If any `markdown-languages.json` file found % by \pkg{kpathsea}\footnote{Local files take precedence. Filenames other -% than \t`markdown-languages.json` may be specified using the -% \t`contentBlocksLanguageMap` Lua option.} contains a record $(k, v)$, then a +% 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$\t`:lower()`${}=k$ is considered to be in a known programming language $v$. +% 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 \t`markdown-languages.json` file +% 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 \t`Languages.json` -% file provided by \cite{sotkov17} is a good starting point. +% exist other creative uses beside syntax highlighting. The `Languages.json` +% file provided by @sotkov17 is a good starting point. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererContentBlockCode{% \markdownRendererContentBlockCodePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Bullet List Renderers} +%#### Bullet List Renderers % The \mdef{markdownRendererUlBegin} macro represents the beginning of a % bulleted list that contains an item with several paragraphs of text (the % list is not tight). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlBegin{% \markdownRendererUlBeginPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererUlBeginTight} macro represents the beginning of a % bulleted 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 \t`false`. The macro receives no arguments. +% is `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlBeginTight{% \markdownRendererUlBeginTightPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererUlItem} macro represents an item in a bulleted % list. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlItem{% \markdownRendererUlItemPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererUlItemEnd} macro represents the end of an item in a % bulleted list. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlItemEnd{% \markdownRendererUlItemEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererUlEnd} macro represents the end of a bulleted list % that contains an item with several paragraphs of text (the list is not % tight). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlEnd{% \markdownRendererUlEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererUlEndTight} macro represents the end of a bulleted % 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 -% \t`false`. The macro receives no arguments. +% `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererUlEndTight{% \markdownRendererUlEndTightPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Ordered List Renderers} +%#### 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). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlBegin{% \markdownRendererOlBeginPrototype}% % \end{macrocode} +% \par +% \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 \t`false`. The macro receives no arguments. +% option is `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlBeginTight{% \markdownRendererOlBeginTightPrototype}% % \end{macrocode} +% \par +% \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 -% \t`false`. The macro receives no arguments. +% `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlItem{% \markdownRendererOlItemPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererOlItemEnd} macro represents the end of an item in % an ordered list. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlItemEnd{% \markdownRendererOlItemEndPrototype}% % \end{macrocode} +% \par +% \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 \t`true`. The macro receives no arguments. +% option is `true`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlItemWithNumber{% \markdownRendererOlItemWithNumberPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % 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). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlEnd{% \markdownRendererOlEndPrototype}% % \end{macrocode} +% \par +% \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 -% \t`false`. The macro receives no arguments. +% `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererOlEndTight{% \markdownRendererOlEndTightPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Definition List Renderers} +%#### Definition List Renderers % The following macros are only produces, when the \Opt{definitionLists} option -% is \t`true`. +% is `true`. % % The \mdef{markdownRendererDlBegin} macro represents the beginning of a % definition list that contains an item with several paragraphs of text (the % list is not tight). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlBegin{% \markdownRendererDlBeginPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlBeginTight} macro represents the beginning of a % definition list that contains an item with several paragraphs of text (the % list is not tight). This macro will only be produced, when the -% \Opt{tightLists} option is \t`false`. The macro receives no arguments. +% \Opt{tightLists} option is `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlBeginTight{% \markdownRendererDlBeginTightPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlItem} macro represents a term in a definition % list. The macro receives a single argument that corresponds to the term % being defined. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlItem{% \markdownRendererDlItemPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlItemEnd} macro represents the end of a list of % definitions for a single term. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlItemEnd{% \markdownRendererDlItemEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlDefinitionBegin} macro represents the beginning % of a definition in a definition list. There can be several definitions for % a single term. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlDefinitionBegin{% \markdownRendererDlDefinitionBeginPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlDefinitionEnd} macro represents the end of a % definition in a definition list. There can be several definitions for a % single term. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlDefinitionEnd{% \markdownRendererDlDefinitionEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlEnd} macro represents the end of a definition % list that contains an item with several paragraphs of text (the list is not % tight). The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlEnd{% \markdownRendererDlEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererDlEndTight} macro represents the end of a % definition 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 \t`false`. The macro receives no arguments. +% option is `false`. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererDlEndTight{% \markdownRendererDlEndTightPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Emphasis Renderers} +%#### 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} % \begin{macrocode} \def\markdownRendererEmphasis{% \markdownRendererEmphasisPrototype}% % \end{macrocode} +% \par +% \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} % \begin{macrocode} \def\markdownRendererStrongEmphasis{% \markdownRendererStrongEmphasisPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Block Quote Renderers} +%#### Block Quote Renderers % The \mdef{markdownRendererBlockQuoteBegin} macro represents the beginning of % a block quote. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererBlockQuoteBegin{% \markdownRendererBlockQuoteBeginPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererBlockQuoteEnd} macro represents the end of a block % quote. The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererBlockQuoteEnd{% \markdownRendererBlockQuoteEndPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Code Block Renderers} +%#### 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} % \begin{macrocode} \def\markdownRendererInputVerbatim{% \markdownRendererInputVerbatimPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererInputFencedCode} macro represents a fenced code % block. This macro will only be produced, when the \Opt{fencedCode} option is -% \t`true`. The macro receives two arguments that correspond to the filename of +% `true`. 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} % \begin{macrocode} \def\markdownRendererInputFencedCode{% \markdownRendererInputFencedCodePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Heading Renderers} +%#### 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} % \begin{macrocode} \def\markdownRendererHeadingOne{% \markdownRendererHeadingOnePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererHeadingTwo} macro represents a second level % heading. The macro receives a single argument that corresponds to the heading % text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHeadingTwo{% \markdownRendererHeadingTwoPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererHeadingThree} macro represents a third level % heading. The macro receives a single argument that corresponds to the heading % text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHeadingThree{% \markdownRendererHeadingThreePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererHeadingFour} macro represents a fourth level % heading. The macro receives a single argument that corresponds to the heading % text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHeadingFour{% \markdownRendererHeadingFourPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererHeadingFive} macro represents a fifth level % heading. The macro receives a single argument that corresponds to the heading % text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHeadingFive{% \markdownRendererHeadingFivePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownRendererHeadingSix} macro represents a sixth level % heading. The macro receives a single argument that corresponds to the heading % text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHeadingSix{% \markdownRendererHeadingSixPrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Horizontal Rule Renderer} +%#### Horizontal Rule Renderer % The \mdef{markdownRendererHorizontalRule} macro represents a horizontal rule. % The macro receives no arguments. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererHorizontalRule{% \markdownRendererHorizontalRulePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Footnote Renderer} +%#### Footnote Renderer % The \mdef{markdownRendererFootnote} macro represents a footnote. This macro -% will only be produced, when the \Opt{footnotes} option is \t`true`. The +% will only be produced, when the \Opt{footnotes} option is `true`. The % macro receives a single argument that corresponds to the footnote text. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererFootnote{% \markdownRendererFootnotePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Parenthesized Citations Renderer} +%#### 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 \t`true`. The macro receives the parameter -% \t`\textbraceleft`\meta{number of citations}\t`\textbraceright` followed by -% \meta{suppress author}\t`\textbraceleft`\meta{prenote}\t`\textbraceright^^A -% \textbraceleft`\meta{postnote}\t`\textbraceright\textbraceleft`\meta{name}^^A -% \t`\textbraceright` repeated \meta{number of citations} times. The -% \meta{suppress author} parameter is either the token \t`-`, when the author's -% name is to be suppressed, or \t`+` otherwise. +% \Opt{citations} option is `true`. 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} % \begin{macrocode} \def\markdownRendererCite{% \markdownRendererCitePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Text Citations Renderer} +%#### 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 \t`true`. The macro receives parameters in the same +% \Opt{citations} option is `true`. The macro receives parameters in the same % format as the \m{markdownRendererCite} macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererTextCite{% \markdownRendererTextCitePrototype}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Token Renderer Prototypes}\label{sec:texrendererprototypes} +%### Token Renderer Prototypes +% \label{sec:texrendererprototypes} % The following \TeX{} macros provide definitions for the token renderers (see % Section \ref{sec:texrenderersuser}) that have not been redefined by the % user. These macros are intended to be redefined by macro package authors % who wish to provide sensible default token renderers. They are also redefined % by the \LaTeX{} and \Hologo{ConTeXt} implementations (see sections % \ref{sec:lateximplementation} and \ref{sec:contextimplementation}). +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererInterblockSeparatorPrototype{}% \def\markdownRendererLineBreakPrototype{}% @@ -1453,50 +5932,71 @@ defaultOptions.underscores = true \def\markdownRendererCitePrototype#1{}% \def\markdownRendererTextCitePrototype#1{}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Logging Facilities} +%### Logging Facilities % The \mdef{markdownInfo}, \mdef{markdownWarning}, and % \mdef{markdownError} macros provide access to logging to the rest of % the macros. Their first argument specifies the text of the info, warning, or % error message. +% +% \end{markdown} % \begin{macrocode} \def\markdownInfo#1{}% \def\markdownWarning#1{}% % \end{macrocode} +% \par +% \begin{markdown} +% % The \m{markdownError} macro receives a second argument that provides a help % text suggesting a remedy to the error. +% +% \end{markdown} % \begin{macrocode} \def\markdownError#1#2{}% % \end{macrocode} +% \par +% \begin{markdown} +% % You may redefine these macros to redirect and process the info, warning, and % error messages. % -% \subsubsection{Miscellanea} +%### Miscellanea % The \mdef{markdownMakeOther} macro is used by the package, when a \TeX{} % engine that does not support direct Lua access is starting to buffer a text. % The plain \TeX{} implementation changes the category code of plain \TeX{} % special characters to other, but there may be other active characters that % may break the output. This macro should temporarily change the category of -% these to \emph{other}. +% these to *other*. +% +% \end{markdown} % \begin{macrocode} \let\markdownMakeOther\relax % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownReadAndConvert} macro implements the \m{markdownBegin} % macro. The first argument specifies the token sequence that will terminate % the markdown input (\m{markdownEnd} in the instance of the \m{markdownBegin} % macro) when the plain \TeX{} special characters have had their category -% changed to \emph{other}. The second argument specifies the token sequence +% changed to *other*. The second argument specifies the token sequence % that will actually be inserted into the document, when the ending token % sequence has been found. +% +% \end{markdown} % \begin{macrocode} \let\markdownReadAndConvert\relax \begingroup % \end{macrocode} -% Locally swap the category code of the backslash symbol (\t`\textbackslash`) -% with the pipe symbol (\t`|`). This is required in order that all the special -% symbols in the first argument of the \t`markdownReadAndConvert` macro have -% the category code \emph{other}. +% \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 in the +% first argument of the `markdownReadAndConvert` macro have the category code +% *other*. +% +% \end{markdown} % \begin{macrocode} \catcode`\|=0\catcode`\\=12% |gdef|markdownBegin{% @@ -1504,24 +6004,27 @@ defaultOptions.underscores = true {|markdownEnd}}% |endgroup % \end{macrocode} +% \begin{markdown} % The macro is exposed in the interface, so that the user can create their own % markdown environments. Due to the way the arguments are passed to Lua (see % Section \ref{sec:directlua}), the first argument may not contain the -% string \t`]]` (regardless of the category code of the bracket symbol (\t`]`)). +% string `]]` (regardless of the category code of the bracket symbol (`]`)). % % The \mdef{markdownMode} macro specifies how the plain \TeX{} implementation % interfaces with the Lua interface. The valid values and their meaning are % as follows: % \begin{itemize} -% \item\t`0` -- Shell escape via the 18 output file stream -% \item\t`1` -- Shell escape via the Lua \luam{os.execute} method -% \item\t`2` -- Direct Lua access +% \item`0` -- Shell escape via the 18 output file stream +% \item`1` -- Shell escape via the Lua \luam{os.execute} method +% \item`2` -- Direct Lua access % \end{itemize} % By defining the macro, the user can coerce the package to use a specific mode. % If the user does not define the macro prior to loading the plain \TeX{} % implementation, the correct value will be automatically detected. The outcome % of changing the value of \m{markdownMode} after the implementation has been % loaded is undefined. +% +% \end{markdown} % \begin{macrocode} \ifx\markdownMode\undefined \ifx\directlua\undefined @@ -1531,9 +6034,13 @@ defaultOptions.underscores = true \fi \fi % \end{macrocode} -% +% \par +% \begin{markdown} +% % The following macros are no longer a part of the plain \TeX{} interface and % are only defined for backwards compatibility: +% +% \end{markdown} % \begin{macrocode} \def\markdownLuaRegisterIBCallback#1{\relax}% \def\markdownLuaUnregisterIBCallback#1{\relax}% @@ -1541,7 +6048,34 @@ defaultOptions.underscores = true % \iffalse %</tex> %<*latex> -% \fi\subsection{\LaTeX{} Interface}\label{sec:latexinterface} +% \fi +% \par +% \begin{markdown} +% +% \LaTeX{} Interface +%------------------- +% \label{sec:latexinterface} +% +% \iffalse +%</latex> +%<*manual> + +LaTeX +----- + +The LaTeX macro package provides additional syntactic sugar on top of the plain +TeX macro package and provides sane default definitions of the token renderers. + +<!-- TODO --> + +### Interfaces + +<!-- TODO --> + +%</manual> +%<*latex> +% \fi +% % The \LaTeX{} interface provides \LaTeX{} environments for the typesetting of % markdown input from within \LaTeX{}, facilities for setting Lua interface % options (see Section \ref{sec:luaoptions}) used during the conversion from @@ -1549,19 +6083,25 @@ defaultOptions.underscores = true % are rendered. The rest of the interface is inherited from the plain \TeX{} % interface (see Section \ref{sec:texinterface}). % -% The \LaTeX{} interface is implemented by the \t`markdown.sty` file, which +% The \LaTeX{} interface is implemented by the `markdown.sty` file, which % can be loaded from the \LaTeX{} document preamble as follows: +% \end{markdown} % \begin{Verbatim}[commandchars=\\\{\}] % \textbackslash{}usepackage[\textrm{\meta{options}}]\{markdown\} % \end{Verbatim} +% \begin{markdown} % where \meta{options} are the \LaTeX{} interface options (see Section % \ref{sec:latexoptions}). Note that \meta{options} inside the \m{usepackage} -% macro may not set the \t`markdownRenderers` (see Section -% \ref{sec:latexrenderers}) and \t`markdownRendererPrototypes` (see Section +% macro may not set the `markdownRenderers` (see Section +% \ref{sec:latexrenderers}) and `markdownRendererPrototypes` (see Section % \ref{sec:latexrendererprototypes}) keys. This limitation is due to the way % \Hologo{LaTeX2e} parses package options. % -% \subsubsection{Typesetting Markdown} +% \end{markdown} +% \par +% \begin{markdown} +% +%### Typesetting Markdown % The interface exposes the \envmdef{markdown} and \envmdef{markdown*} % \LaTeX{} environments, and redefines the \m{markdownInput} command. % @@ -1569,11 +6109,15 @@ defaultOptions.underscores = true % typeset markdown document fragments. The starred version of the % \envm{markdown} environment accepts \LaTeX{} interface options (see % Section \ref{sec:latexoptions}) as its only argument. These options will -% only influnce this markdown document fragment. +% only influence this markdown document fragment. +% +% \end{markdown} % \begin{macrocode} \newenvironment{markdown}\relax\relax \newenvironment{markdown*}[1]\relax\relax % \end{macrocode} +% \markdownBegin +% % You may prepend your own code to the \m{markdown} macro and append your own % code to the \m{endmarkdown} macro to produce special effects before and after % the \envm{markdown} \LaTeX{} environment (and likewise for the starred @@ -1585,7 +6129,7 @@ defaultOptions.underscores = true % % The following example \LaTeX{} code showcases the usage of the % \envm{markdown} and \envm{markdown*} environments: -% \begin{Verbatim} +% ``` tex % \documentclass{article} \documentclass{article} % \usepackage{markdown} \usepackage{markdown} % \begin{document} \begin{document} @@ -1595,7 +6139,7 @@ defaultOptions.underscores = true % \end{markdown} \end{markdown*} % % ... % ... % \end{document} \end{document} -% \end{Verbatim} +% ``````` % % The \m{markdownInput} macro accepts a single mandatory parameter containing % the filename of a markdown document and expands to the result of the @@ -1607,7 +6151,7 @@ defaultOptions.underscores = true % % The following example \LaTeX{} code showcases the usage of the % \m{markdownInput} macro: -% \begin{Verbatim} +% ``` tex % \documentclass{article} % \usepackage{markdown} % \begin{document} @@ -1615,13 +6159,26 @@ defaultOptions.underscores = true % \markdownInput[smartEllipses]{hello.md} % % ... % \end{document} -% \end{Verbatim} +% ``````` +% +%### Options +% \label{sec:latexoptions} +% +% \iffalse +%</latex> +%<*manual> + +### Options + +<!-- TODO --> + +%</manual> +%<*latex> +% \fi % -% \subsubsection{Options}\label{sec:latexoptions} % The \LaTeX{} options are represented by a comma-delimited list of -% \meta{\meta{key}=\meta{value}} pairs. For boolean options, the -% \meta{=\meta{value}} part is optional, and \meta{\meta{key}} will be -% interpreted as \meta{\meta{key}=true}. +% \meta{key}`=`\meta{value} pairs. For boolean options, the `=`\meta{value} +% part is optional, and \meta{key} will be interpreted as \meta{key}`=true`. % % The \LaTeX{} options map directly to the options recognized by the plain % \TeX{} interface (see Section \ref{sec:texoptions}) and to the markdown token @@ -1632,14 +6189,20 @@ defaultOptions.underscores = true % Section \ref{sec:latexinterface}), when using the \envm{markdown*} \LaTeX{} % environment, or via the \mdef{markdownSetup} macro. The \m{markdownSetup} % macro receives the options to set up as its only argument. +% +% \markdownEnd % \begin{macrocode} \newcommand\markdownSetup[1]{% \setkeys{markdownOptions}{#1}}% % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Plain \TeX{} Interface Options} +%#### Plain \TeX{} Interface Options % The following options map directly to the option macros exposed by the plain % \TeX{} interface (see Section \ref{sec:texoptions}). +% +% \end{markdown} % \begin{macrocode} \define@key{markdownOptions}{helperScriptFileName}{% \def\markdownOptionHelperScriptFileName{#1}}% @@ -1695,24 +6258,44 @@ defaultOptions.underscores = true \def\markdownOptionTightLists{#1}}% \define@key{markdownOptions}{underscores}[true]{% \def\markdownOptionUnderscores{#1}}% +\define@key{markdownOptions}{stripPercentSigns}[true]{% + \def\markdownOptionStripPercentSigns{#1}}% % \end{macrocode} +% \par +% \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of % plain \TeX{} interface options \m{markdownOptionHybrid}, % \m{markdownOptionSmartEllipses}, and \m{markdownOptionCacheDir}. -% \begin{Verbatim} +% ``` tex % \markdownSetup{ % hybrid, % smartEllipses, % cacheDir = /tmp, % } -% \end{Verbatim} +% ``````` % -% \paragraph{Plain \TeX{} Markdown Token Renderers}\label{sec:latexrenderers} -% The \LaTeX{} interface recognizes an option with the \t`renderers` key, +%#### Plain \TeX{} Markdown Token Renderers +% \label{sec:latexrenderers} +% +% \iffalse +%</latex> +%<*manual> + +### Token renderers + +<!-- TODO --> + +%</manual> +%<*latex> +% \fi +% +% The \LaTeX{} interface recognizes an option with the `renderers` key, % whose value must be a list of options that map directly to the markdown token % renderer macros exposed by the plain \TeX{} interface (see Section % \ref{sec:texrenderersuser}). +% +% \end{markdown} % \begin{macrocode} \define@key{markdownRenderers}{interblockSeparator}{% \renewcommand\markdownRendererInterblockSeparator{#1}}% @@ -1831,25 +6414,29 @@ defaultOptions.underscores = true \define@key{markdownRenderers}{textCite}{% \renewcommand\markdownRendererTextCite[1]{#1}}% % \end{macrocode} +% \par +% \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of the % \m{markdownRendererLink} and \m{markdownRendererEmphasis} markdown token % renderers. -% \begin{Verbatim} +% ``` tex % \markdownSetup{ % renderers = { % link = {#4}, % Render links as the link title. % emphasis = {\emph{#1}}, % Render emphasized text via `\emph`. % } % } -% \end{Verbatim} +% ``````` % -% \paragraph{Plain \TeX{} Markdown Token Renderer Prototypes} +%#### Plain \TeX{} Markdown Token Renderer Prototypes % \label{sec:latexrendererprototypes} -% The \LaTeX{} interface recognizes an option with the \t`rendererPrototypes` +% The \LaTeX{} interface recognizes an option with the `rendererPrototypes` % key, whose value must be a list of options that map directly to the markdown % token renderer prototype macros exposed by the plain \TeX{} interface (see % Section \ref{sec:texrendererprototypes}). +% +% \end{markdown} % \begin{macrocode} \define@key{markdownRendererPrototypes}{interblockSeparator}{% \renewcommand\markdownRendererInterblockSeparatorPrototype{#1}}% @@ -1968,47 +6555,89 @@ defaultOptions.underscores = true \define@key{markdownRendererPrototypes}{textCite}{% \renewcommand\markdownRendererTextCitePrototype[1]{#1}}% % \end{macrocode} +% \par +% \begin{markdown} % % The following example \LaTeX{} code showcases a possible configuration of the % \m{markdownRendererImagePrototype} and \m{markdownRendererCodeSpanPrototype} % markdown token renderer prototypes. -% \begin{Verbatim} +% ``` tex % \markdownSetup{ % rendererPrototypes = { % image = {\includegraphics{#2}}, % codeSpan = {\texttt{#1}}, % Render inline code via `\texttt`. % } % } -% \end{Verbatim} +% ``````` % % \iffalse %</latex> %<*context> -% \fi\subsection{\Hologo{ConTeXt} Interface}\label{sec:contextinterface} +% \fi +% \Hologo{ConTeXt} Interface +%--------------------------- +% \label{sec:contextinterface} +% +% \iffalse +%</context> +%<*manual> + +ConTeXt +------- + +The ConTeXt macro package provides additional syntactic sugar on top of the +plain TeX macro package and provides sane default definitions of the token +renderers. + +### Interfaces + +<!-- TODO --> + +### Options + +<!-- TODO --> + +### Token renderers + +<!-- TODO --> + +%</manual> +%<*context> +% \fi +% % The \Hologo{ConTeXt} interface provides a start-stop macro pair for the % typesetting of markdown input from within \Hologo{ConTeXt}. The rest of the % interface is inherited from the plain \TeX{} interface (see Section % \ref{sec:texinterface}). +% +% \end{markdown} % \begin{macrocode} \writestatus{loading}{ConTeXt User Module / markdown}% \unprotect % \end{macrocode} +% \par +% \begin{markdown} % % The \Hologo{ConTeXt} interface is implemented by the -% \t`t-markdown.tex` \Hologo{ConTeXt} module file that can be loaded as follows: -% \begin{Verbatim} +% `t-markdown.tex` \Hologo{ConTeXt} module file that can be loaded as follows: +% ``` tex % \usemodule[t][markdown] -% \end{Verbatim} -% It is expected that the special plain \TeX{} characters have the expected -% category codes, when \m{input}ting the file. +% ``````` +% \noindent It is expected that the special plain \TeX{} characters have the +% expected category codes, when \m{input}ting the file. % -% \subsubsection{Typesetting Markdown} +%### Typesetting Markdown % The interface exposes the \mdef{startmarkdown} and \mdef{stopmarkdown} macro % pair for the typesetting of a markdown document fragment. +% +% \end{markdown} % \begin{macrocode} \let\startmarkdown\relax \let\stopmarkdown\relax % \end{macrocode} +% \par +% \begin{markdown} +% % You may prepend your own code to the \m{startmarkdown} macro and redefine the % \m{stopmarkdown} macro to produce special effects before and after the % markdown block. @@ -2019,24 +6648,30 @@ defaultOptions.underscores = true % % The following example \Hologo{ConTeXt} code showcases the usage of the % \m{startmarkdown} and \m{stopmarkdown} macros: -% \begin{Verbatim} +% ``` tex % \usemodule[t][markdown] % \starttext % \startmarkdown % _Hello_ **world** ... % \stopmarkdown % \stoptext -% \end{Verbatim} -% -% \section{Technical Documentation}\label{sec:implementation} -% This part of the manual describes the implementation of the interfaces +% ``````` +% +% Implementation +%=============== +% \label{sec:implementation} +% This part of the documentation describes the implementation of the interfaces % exposed by the package (see Section \ref{sec:interfaces}) and is aimed at the % developers of the package, as well as the curious users. % % \iffalse %</context> %<*lua> -% \fi\subsection{Lua Implementation}\label{sec:luaimplementation} +% \fi +% +% Lua Implementation +%------------------- +% \label{sec:luaimplementation} % The Lua implementation implements \luamdef{writer} and \luamdef{reader} % objects that provide the conversion from markdown to plain \TeX{}. % @@ -2046,6 +6681,7 @@ defaultOptions.underscores = true % were hidden behind the converter functions exposed by the Lua interface (see % Section \ref{sec:luainterface}). % +% \end{markdown} % \begin{macrocode} local upper, gsub, format, length = string.upper, string.gsub, string.format, string.len @@ -2054,30 +6690,42 @@ local P, R, S, V, C, Cg, Cb, Cmt, Cc, Ct, B, Cs, any = lpeg.P, lpeg.R, lpeg.S, lpeg.V, lpeg.C, lpeg.Cg, lpeg.Cb, lpeg.Cmt, lpeg.Cc, lpeg.Ct, lpeg.B, lpeg.Cs, lpeg.P(1) % \end{macrocode} -% -% \subsubsection{Utility Functions} +% \par +% \begin{markdown} +% +%### Utility Functions % This section documents the utility functions used by the plain \TeX{} % writer and the markdown reader. These functions are encapsulated in the -% \t`util` object. The functions were originally located in the -% \t`lunamark/util.lua` file in the Lunamark Lua module. +% `util` object. The functions were originally located in the +% `lunamark/util.lua` file in the Lunamark Lua module. +% +% \end{markdown} % \begin{macrocode} local util = {} % \end{macrocode} -% -% The \luamdef{util.err} method prints an error message \t`msg` and exits. -% If \t`exit_code` is provided, it specifies the exit code. Otherwise, the +% \par +% \begin{markdown} +% +% The \luamdef{util.err} method prints an error message `msg` and exits. +% If `exit_code` is provided, it specifies the exit code. Otherwise, the % exit code will be 1. +% +% \end{markdown} % \begin{macrocode} function util.err(msg, exit_code) io.stderr:write("markdown.lua: " .. msg .. "\n") os.exit(exit_code or 1) end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.cache} method computes the digest of \t`string` and -% \t`salt`, adds the \t`suffix` and looks into the directory \t`dir`, whether a +% The \luamdef{util.cache} method computes the digest of `string` and +% `salt`, adds the `suffix` and looks into the directory `dir`, whether a % file with such a name exists. If it does not, it gets created with -% \t`transform(string)` as its content. The filename is then returned. +% `transform(string)` as its content. The filename is then returned. +% +% \end{markdown} % \begin{macrocode} function util.cache(dir, string, salt, transform, suffix) local digest = md5.sumhexa(string .. (salt or "")) @@ -2095,9 +6743,13 @@ function util.cache(dir, string, salt, transform, suffix) return name end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.table_copy} method creates a shallow copy of a table \t`t` +% The \luamdef{util.table_copy} method creates a shallow copy of a table `t` % and its metatable. +% +% \end{markdown} % \begin{macrocode} function util.table_copy(t) local u = { } @@ -2105,11 +6757,15 @@ function util.table_copy(t) return setmetatable(u, getmetatable(t)) end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.expand_tabs_in_line} expands tabs in string \t`s`. If -% \t`tabstop` is specified, it is used as the tab stop width. Otherwise, +% The \luamdef{util.expand_tabs_in_line} expands tabs in string `s`. If +% `tabstop` is specified, it is used as the tab stop width. Otherwise, % the tab stop width of 4 characters is used. The method is a copy of the tab -% expansion algorithm from \cite[Chapter~21]{ierusalimschy13}. +% expansion algorithm from @ierusalimschy13 [Chapter 21]. +% +% \end{markdown} % \begin{macrocode} function util.expand_tabs_in_line(s, tabstop) local tab = tabstop or 4 @@ -2121,11 +6777,15 @@ function util.expand_tabs_in_line(s, tabstop) end)) end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.walk} method walks a rope \t`t`, applying a function \t`f` +% The \luamdef{util.walk} method walks a rope `t`, applying a function `f` % to each leaf element in order. A rope is an array whose elements may be % ropes, strings, numbers, or functions. If a leaf element is a function, call % it and get the return value before proceeding. +% +% \end{markdown} % \begin{macrocode} function util.walk(t, f) local typ = type(t) @@ -2150,9 +6810,13 @@ function util.walk(t, f) end end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.flatten} method flattens an array \t`ary` that does not +% The \luamdef{util.flatten} method flattens an array `ary` that does not % contain cycles and returns the result. +% +% \end{markdown} % \begin{macrocode} function util.flatten(ary) local new = {} @@ -2168,10 +6832,14 @@ function util.flatten(ary) return new end % \end{macrocode} +% \par +% \begin{markdown} % -% The \luamdef{util.rope_to_string} method converts a rope \t`rope` to a +% The \luamdef{util.rope_to_string} method converts a rope `rope` to a % string and returns it. For the definition of a rope, see the definition of % the \luam{util.walk} method. +% +% \end{markdown} % \begin{macrocode} function util.rope_to_string(rope) local buffer = {} @@ -2179,9 +6847,13 @@ function util.rope_to_string(rope) return table.concat(buffer) end % \end{macrocode} +% \par +% \begin{markdown} % % The \luamdef{util.rope_last} method retrieves the last item in a rope. For % the definition of a rope, see the definition of the \luam{util.walk} method. +% +% \end{markdown} % \begin{macrocode} function util.rope_last(rope) if #rope == 0 then @@ -2196,10 +6868,14 @@ function util.rope_last(rope) end end % \end{macrocode} +% \par +% \begin{markdown} +% +% Given an array `ary` and a string `x`, the \luamdef{util.intersperse} +% method returns an array `new`, such that `ary[i] == new[2*(i-1)+1]` and +% `new[2*i] == x` for all $1\leq`i`\leq`#ary`$. % -% Given an array \t`ary` and a string \t`x`, the \luamdef{util.intersperse} -% method returns an array \t`new`, such that \t`ary[i] == new[2*(i-1)+1]` and -% \t`new[2*i] == x` for all $1\leq\t`i`\leq\t`\#ary`$. +% \end{markdown} % \begin{macrocode} function util.intersperse(ary, x) local new = {} @@ -2214,10 +6890,14 @@ function util.intersperse(ary, x) return new end % \end{macrocode} -% -% Given an array \t`ary` and a function \t`f`, the \luamdef{util.map} method -% returns an array \t`new`, such that \t`new[i] == f(ary[i])` for all -% $1\leq\t`i`\leq\t`\#ary`$. +% \par +% \begin{markdown} +% +% Given an array `ary` and a function `f`, the \luamdef{util.map} method +% returns an array `new`, such that `new[i] == f(ary[i])` for all +% $1\leq`i`\leq`#ary`$. +% +% \end{markdown} % \begin{macrocode} function util.map(ary, f) local new = {} @@ -2227,39 +6907,48 @@ function util.map(ary, f) return new end % \end{macrocode} +% \par +% \begin{markdown} % -% Given a table \t`char_escapes` mapping escapable characters to escaped -% strings and optionally a table \t`string_escapes` mapping escapable strings +% Given a table `char_escapes` mapping escapable characters to escaped +% strings and optionally a table `string_escapes` mapping escapable strings % to escaped strings, the \luamdef{util.escaper} method returns an escaper % function that escapes all occurances of escapable strings and characters (in % this order). -% -% The method uses \pkg{LPeg}, which is faster than the Lua \t`string.gsub` +% +% The method uses \pkg{LPeg}, which is faster than the Lua `string.gsub` % built-in method. +% +% \end{markdown} % \begin{macrocode} function util.escaper(char_escapes, string_escapes) % \end{macrocode} +% \begin{markdown} % Build a string of escapable characters. +% \end{markdown} % \begin{macrocode} local char_escapes_list = "" for i,_ in pairs(char_escapes) do char_escapes_list = char_escapes_list .. i end % \end{macrocode} -% Create an \pkg{LPeg} capture \t`escapable` that produces the escaped string +% \begin{markdown} +% Create an \pkg{LPeg} capture `escapable` that produces the escaped string % corresponding to the matched escapable character. +% \end{markdown} % \begin{macrocode} local escapable = S(char_escapes_list) / char_escapes % \end{macrocode} -% If \t`string_escapes` is provided, turn \t`escapable` into the -% {\catcode`\_=8\[ -% \sum_{(\t`k`,\t`v`)\in\t`string\_escapes`}\t`P(k) / v` + \t`escapable` -% \]}^^A -% capture that replaces any occurance of the string \t`k` with the string -% \t`v` for each $(\t`k`, \t`v`)\in\t`string\_escapes`$. Note that the pattern +% \begin{markdown} +% If `string_escapes` is provided, turn `escapable` into the +% $$\sum_{(`k`,`v`)\in`string_escapes`}`P(k) / v` + `escapable`$$ +% capture that replaces any occurance of the string `k` with the string +% `v` for each $(`k`, `v`)\in`string_escapes`$. Note that the pattern % summation is not commutative and its operands are inspected in the % summation order during the matching. As a corrolary, the strings always % take precedence over the characters. +% +% \end{markdown} % \begin{macrocode} if string_escapes then for k,v in pairs(string_escapes) do @@ -2267,22 +6956,30 @@ function util.escaper(char_escapes, string_escapes) end end % \end{macrocode} -% Create an \pkg{LPeg} capture \t`escape_string` that captures anything -% \t`escapable` does and matches any other unmatched characters. +% \begin{markdown} +% Create an \pkg{LPeg} capture `escape_string` that captures anything +% `escapable` does and matches any other unmatched characters. +% \end{markdown} % \begin{macrocode} local escape_string = Cs((escapable + any)^0) % \end{macrocode} -% Return a function that matches the input string \t`s` against the -% \t`escape_string` capture. +% \begin{markdown} +% Return a function that matches the input string `s` against the +% `escape_string` capture. +% \end{markdown} % \begin{macrocode} return function(s) return lpeg.match(escape_string, s) end end % \end{macrocode} +% \par +% \begin{markdown} % % The \luamdef{util.pathname} method produces a pathname out of a directory -% name \t`dir` and a filename \t`file` and returns it. +% name `dir` and a filename `file` and returns it. +% +% \end{markdown} % \begin{macrocode} function util.pathname(dir, file) if #dir == 0 then @@ -2292,11 +6989,16 @@ function util.pathname(dir, file) end end % \end{macrocode} -% \subsubsection{\textsc{html} Entities} +% \par +% \begin{markdown} +% +%### \textsc{html} Entities % This section documents the \textsc{html} entities recognized by the -% markdown reader. These functions are encapsulated in the \t`entities` +% markdown reader. These functions are encapsulated in the `entities` % object. The functions were originally located in the -% \t`lunamark/entities.lua` file in the Lunamark Lua module. +% `lunamark/entities.lua` file in the Lunamark Lua module. +% +% \end{markdown} % \begin{macrocode} local entities = {} @@ -2552,143 +7254,216 @@ local character_entities = { ["diams"] = 0x2666, } % \end{macrocode} +% \par +% \begin{markdown} % -% Given a string \t`s` of decimal digits, the \luamdef{entities.dec_entity} +% Given a string `s` of decimal digits, the \luamdef{entities.dec_entity} % returns the corresponding \textsc{utf}8-encoded Unicode codepoint. +% +% \end{markdown} % \begin{macrocode} function entities.dec_entity(s) return unicode.utf8.char(tonumber(s)) end % \end{macrocode} +% \par +% \begin{markdown} % -% Given a string \t`s` of hexadecimal digits, the +% Given a string `s` of hexadecimal digits, the % \luamdef{entities.hex_entity} returns the corresponding % \textsc{utf}8-encoded Unicode codepoint. +% +% \end{markdown} % \begin{macrocode} function entities.hex_entity(s) return unicode.utf8.char(tonumber("0x"..s)) end % \end{macrocode} +% \par +% \begin{markdown} % -% Given a character entity name \t`s` (like \t`ouml`), the +% Given a character entity name `s` (like `ouml`), the % \luamdef{entities.char_entity} returns the corresponding % \textsc{utf}8-encoded Unicode codepoint. +% +% \end{markdown} % \begin{macrocode} function entities.char_entity(s) local n = character_entities[s] return unicode.utf8.char(n) end % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Plain \TeX{} Writer}\label{sec:texwriter} +%### Plain \TeX{} Writer +% \label{sec:texwriter} % This section documents the \luam{writer} object, which implements the % routines for producing the \TeX{} output. The object is an amalgamate of the % generic, \TeX{}, \LaTeX{} writer objects that were located in the -% \t`lunamark/writer/generic.lua`, \t`lunamark/writer/tex.lua`, and -% \t`lunamark/writer/latex.lua` files in the Lunamark Lua module. +% `lunamark/writer/generic.lua`, `lunamark/writer/tex.lua`, and +% `lunamark/writer/latex.lua` files in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section % \ref{sec:luainterface}), the \luam{writer} object is exported, so that the % curious user could easily tinker with the methods of the objects produced by % the \luam{writer.new} method described below. The user should be aware, % however, that the implementation may change in a future revision. +% +% \end{markdown} % \begin{macrocode} M.writer = {} % \end{macrocode} +% \par +% \begin{markdown} % % The \luamdef{writer.new} method creates and returns a new \TeX{} writer % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) \t`options`. When \t`options` are unspecified, it is +% \ref{sec:luaoptions}) `options`. When `options` are unspecified, it is % assumed that an empty table was passed to the method. % % The objects produced by the \luam{writer.new} method expose instance methods % and variables of their own. As a convention, I will refer to these -% \meta{member}s as \t`writer->`\meta{member}. +% \meta{member}s as `writer->`\meta{member}. +% +% \end{markdown} % \begin{macrocode} function M.writer.new(options) local self = {} options = options or {} % \end{macrocode} +% \par +% \begin{markdown} % -% Make the \t`options` table inherit from the \luam{defaultOptions} table. +% Make the `options` table inherit from the \luam{defaultOptions} table. +% +% \end{markdown} % \begin{macrocode} setmetatable(options, { __index = function (_, key) return defaultOptions[key] end }) % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->suffix} as the suffix of the produced cache files. +% +% \end{markdown} % \begin{macrocode} self.suffix = ".tex" % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->space} as the output format of a space character. +% +% \end{markdown} % \begin{macrocode} self.space = " " % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->nbsp} as the output format of a non-breaking space % character. +% +% \end{markdown} % \begin{macrocode} self.nbsp = "\\markdownRendererNbsp{}" % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->plain} as a function that will transform an input -% plain text block \t`s` to the output format. +% plain text block `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.plain(s) return s end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->paragraph} as a function that will transform an -% input paragraph \t`s` to the output format. +% input paragraph `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.paragraph(s) return s end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->pack} as a function that will take the filename -% \t`name` of the output file prepared by the reader and transform it to the +% `name` of the output file prepared by the reader and transform it to the % output format. +% +% \end{markdown} % \begin{macrocode} function self.pack(name) - return [[\input"]] .. name .. [["\relax]] + return [[\input"]] .. name .. [["\relax{}]] end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->interblocksep} as the output format of a block % element separator. +% +% \end{markdown} % \begin{macrocode} self.interblocksep = "\\markdownRendererInterblockSeparator\n{}" % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->eof} as the end of file marker in the output format. +% +% \end{markdown} % \begin{macrocode} self.eof = [[\relax]] % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->linebreak} as the output format of a forced line break. +% +% \end{markdown} % \begin{macrocode} self.linebreak = "\\markdownRendererLineBreak\n{}" % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->ellipsis} as the output format of an ellipsis. +% +% \end{markdown} % \begin{macrocode} self.ellipsis = "\\markdownRendererEllipsis{}" % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->hrule} as the output format of a horizontal rule. +% +% \end{markdown} % \begin{macrocode} self.hrule = "\\markdownRendererHorizontalRule{}" % \end{macrocode} +% \par +% \begin{markdown} % % Define a table \luamdef{escaped_chars} containing the mapping from special -% plain \TeX{} characters (including the active pipe character (\t`|`) of +% plain \TeX{} characters (including the active pipe character (`|`) of % \Hologo{ConTeXt}) to their escaped variants. Define tables % \luamdef{escaped_minimal_chars} and \luamdef{escaped_minimal_strings} % containing the mapping from special plain characters and character strings % that need to be escaped even in content that will not be typeset. +% +% \end{markdown} % \begin{macrocode} local escaped_chars = { ["{"] = "\\markdownRendererLeftBrace{}", @@ -2720,22 +7495,31 @@ function M.writer.new(options) ["^^"] = "\\markdownRendererCircumflex\\markdownRendererCircumflex ", } % \end{macrocode} +% \par +% \begin{markdown} +% % Use the \luam{escaped_chars} table to create an escaper function % \luamdef{escape} and the \luam{escaped_minimal_chars} and % \luam{escaped_minimal_strings} tables to create an escaper function % \luamdef{escape_minimal}. +% +% \end{markdown} % \begin{macrocode} local escape = util.escaper(escaped_chars) local escape_citation = util.escaper(escaped_citation_chars, escaped_minimal_strings) local escape_uri = util.escaper(escaped_uri_chars, escaped_minimal_strings) % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->string} as a function that will transform an input -% plain text span \t`s` to the output format and \luamdef{writer->uri} as a -% function that will transform an input \acro{uri} \t`u` to the output format. -% If the \Opt{hybrid} option is \t`true`, use identity functions. Otherwise, +% plain text span `s` to the output format and \luamdef{writer->uri} as a +% function that will transform an input \acro{uri} `u` to the output format. +% If the \Opt{hybrid} option is `true`, use identity functions. Otherwise, % use the \luam{escape} and \luam{escape_minimal} functions. +% +% \end{markdown} % \begin{macrocode} if options.hybrid then self.string = function(s) return s end @@ -2747,18 +7531,26 @@ function M.writer.new(options) self.uri = escape_uri end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->code} as a function that will transform an input -% inlined code span \t`s` to the output format. +% inlined code span `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.code(s) return {"\\markdownRendererCodeSpan{",escape(s),"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->link} as a function that will transform an input -% hyperlink to the output format, where \t`lab` corresponds to the label, -% \t`src` to \acro{uri}, and \t`tit` to the title of the link. +% hyperlink to the output format, where `lab` corresponds to the label, +% `src` to \acro{uri}, and `tit` to the title of the link. +% +% \end{markdown} % \begin{macrocode} function self.link(lab,src,tit) return {"\\markdownRendererLink{",lab,"}", @@ -2767,10 +7559,14 @@ function M.writer.new(options) "{",self.string(tit or ""),"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->image} as a function that will transform an input -% image to the output format, where \t`lab` corresponds to the label, \t`src` -% to the \acro{url}, and \t`tit` to the title of the image. +% image to the output format, where `lab` corresponds to the label, `src` +% to the \acro{url}, and `tit` to the title of the image. +% +% \end{markdown} % \begin{macrocode} function self.image(lab,src,tit) return {"\\markdownRendererImage{",lab,"}", @@ -2779,21 +7575,25 @@ function M.writer.new(options) "{",self.string(tit or ""),"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % The \luamdef{languages_json} table maps programming language filename % extensions to fence infostrings. All \luam{options.contentBlocksLanguageMap} % files located by \pkg{kpathsea} are loaded into a chain of tables. % \luam{languages_json} corresponds to the first table and is chained with % the rest via Lua metatables. +% +% \end{markdown} % \begin{macrocode} local languages_json = (function() - local kpse = require('kpse') - kpse.set_program_name('luatex') + local kpse = require("kpse") + kpse.set_program_name("luatex") local base, prev, curr for _, file in ipairs{kpse.lookup(options.contentBlocksLanguageMap, { all=true })} do - json = assert(io.open(file, "r")):read("*all") - :gsub('("[^\n]-"):','[%1]=') + json = io.open(file, "r"):read("*all") + :gsub('("[^\n]-"):','[%1]=') curr = (function() local _ENV={ json=json, load=load } -- run in sandbox return load("return "..json)() @@ -2810,12 +7610,16 @@ local languages_json = (function() return base or {} end)() % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->contentblock} as a function that will transform an -% input iA\,Writer content block to the output format, where \t`src` -% corresponds to the \acro{uri} prefix, \t`suf` to the \acro{uri} extension, -% \t`type` to the type of the content block (\t`localfile` or \t`onlineimage`), -% and \t`tit` to the title of the content block. +% input iA\,Writer content block to the output format, where `src` +% corresponds to the \acro{uri} prefix, `suf` to the \acro{uri} extension, +% `type` to the type of the content block (`localfile` or `onlineimage`), +% and `tit` to the title of the content block. +% +% \end{markdown} % \begin{macrocode} function self.contentblock(src,suf,type,tit) src = src.."."..suf @@ -2839,10 +7643,14 @@ end)() end end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->bulletlist} as a function that will transform an input -% bulleted list to the output format, where \t`items` is an array of the list -% items and \t`tight` specifies, whether the list is tight or not. +% bulleted list to the output format, where `items` is an array of the list +% items and `tight` specifies, whether the list is tight or not. +% +% \end{markdown} % \begin{macrocode} local function ulitem(s) return {"\\markdownRendererUlItem ",s, @@ -2864,12 +7672,16 @@ end)() end end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->ollist} as a function that will transform an input -% ordered list to the output format, where \t`items` is an array of the list -% items and \t`tight` specifies, whether the list is tight or not. If the -% optional parameter \t`startnum` is present, it should be used as the number +% ordered list to the output format, where `items` is an array of the list +% items and `tight` specifies, whether the list is tight or not. If the +% optional parameter `startnum` is present, it should be used as the number % of the first list item. +% +% \end{markdown} % \begin{macrocode} local function olitem(s,num) if num ~= nil then @@ -2900,21 +7712,29 @@ end)() end end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->inline_html} and \luamdef{writer->display_html} % as functions that will transform an inline or block \textsc{html} element -% respectively to the output format, where \t`html` is the \textsc{html} +% respectively to the output format, where `html` is the \textsc{html} % input. +% +% \end{markdown} % \begin{macrocode} function self.inline_html(html) return "" end function self.display_html(html) return "" end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->definitionlist} as a function that will transform an -% input definition list to the output format, where \t`items` is an array of -% tables, each of the form \t`\{ term = t, definitions = defs \}`, where \t`t` -% is a term and \t`defs` is an array of definitions. \t`tight` specifies, +% input definition list to the output format, where `items` is an array of +% tables, each of the form `{ term = t, definitions = defs }`, where `t` +% is a term and `defs` is an array of definitions. `tight` specifies, % whether the list is tight or not. +% +% \end{markdown} % \begin{macrocode} local function dlitem(term, defs) local retVal = {"\\markdownRendererDlItem{",term,"}"} @@ -2940,53 +7760,77 @@ end)() end end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->emphasis} as a function that will transform an -% emphasized span \t`s` of input text to the output format. +% emphasized span `s` of input text to the output format. +% +% \end{markdown} % \begin{macrocode} function self.emphasis(s) return {"\\markdownRendererEmphasis{",s,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->strong} as a function that will transform a strongly -% emphasized span \t`s` of input text to the output format. +% emphasized span `s` of input text to the output format. +% +% \end{markdown} % \begin{macrocode} function self.strong(s) return {"\\markdownRendererStrongEmphasis{",s,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->blockquote} as a function that will transform an -% input block quote \t`s` to the output format. +% input block quote `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.blockquote(s) return {"\\markdownRendererBlockQuoteBegin\n",s, "\n\\markdownRendererBlockQuoteEnd "} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->verbatim} as a function that will transform an -% input code block \t`s` to the output format. +% input code block `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.verbatim(s) local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim") return {"\\markdownRendererInputVerbatim{",name,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->codeFence} as a function that will transform an -% input fenced code block \t`s` with the infostring \t`i` to the output +% input fenced code block `s` with the infostring `i` to the output % format. +% +% \end{markdown} % \begin{macrocode} function self.fencedCode(i, s) local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim") return {"\\markdownRendererInputFencedCode{",name,"}{",i,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->heading} as a function that will transform an -% input heading \t`s` at level \t`level` to the output format. +% input heading `s` at level `level` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.heading(s,level) local cmd @@ -3008,28 +7852,36 @@ end)() return {cmd,"{",s,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->note} as a function that will transform an -% input footnote \t`s` to the output format. +% input footnote `s` to the output format. +% +% \end{markdown} % \begin{macrocode} function self.note(s) return {"\\markdownRendererFootnote{",s,"}"} end % \end{macrocode} +% \par +% \begin{markdown} % % Define \luamdef{writer->citations} as a function that will transform an -% input array of citations \t`cites` to the output format. If \t`text_cites` -% is \t`true`, the citations should be rendered in-text, when applicable. -% The \t`cites` array contains tables with the following keys and values: +% input array of citations `cites` to the output format. If `text_cites` +% is `true`, the citations should be rendered in-text, when applicable. +% The `cites` array contains tables with the following keys and values: % \begin{itemize} -% \item\t`suppress_author` -- If the value of the key is true, then the +% \item`suppress_author` -- If the value of the key is true, then the % author of the work should be omitted in the citation, when applicable. -% \item\t`prenote` -- The value of the key is either \t`nil` or a rope +% \item`prenote` -- The value of the key is either `nil` or a rope % that should be inserted before the citation. -% \item\t`postnote` -- The value of the key is either \t`nil` or a rope +% \item`postnote` -- The value of the key is either `nil` or a rope % that should be inserted after the citation. -% \item\t`name` -- The value of this key is the citation name. +% \item`name` -- The value of this key is the citation name. % \end{itemize} +% +% \end{markdown} % \begin{macrocode} function self.citations(text_cites, cites) local buffer = {"\\markdownRenderer", text_cites and "TextCite" or "Cite", @@ -3044,13 +7896,23 @@ end)() return self end % \end{macrocode} -% \subsubsection{Parsers} +% \par +% \begin{markdown} +% +%### Parsers % The \luamdef{parsers} hash table stores \acro{peg} patterns that are % static and can be reused between different \luam{reader} objects. +% +% \end{markdown} % \begin{macrocode} local parsers = {} % \end{macrocode} -% \paragraph{Basic Parsers} +% \par +% \begin{markdown} +% +%#### Basic Parsers +% +% \end{markdown} % \begin{macrocode} parsers.percent = P("%") parsers.at = P("@") @@ -3146,7 +8008,12 @@ parsers.indented_blocks = function(bl) * (parsers.blankline^1 + parsers.eof) ) end % \end{macrocode} -% \paragraph{Parsers Used for Markdown Lists} +% \par +% \begin{markdown} +% +%#### Parsers Used for Markdown Lists +% +% \end{markdown} % \begin{macrocode} parsers.bulletchar = C(parsers.plus + parsers.asterisk + parsers.dash) @@ -3161,7 +8028,12 @@ parsers.bullet = ( parsers.bulletchar * #parsers.spacing * parsers.bulletchar * #parsers.spacing ) % \end{macrocode} -% \paragraph{Parsers Used for Markdown Code Spans} +% \par +% \begin{markdown} +% +%#### Parsers Used for Markdown Code Spans +% +% \end{markdown} % \begin{macrocode} parsers.openticks = Cg(parsers.backtick^1, "ticks") @@ -3181,7 +8053,12 @@ parsers.intickschar = (parsers.any - S(" \n\r`")) parsers.inticks = parsers.openticks * parsers.space^-1 * C(parsers.intickschar^0) * parsers.closeticks % \end{macrocode} -% \paragraph{Parsers Used for Fenced Code Blocks} +% \par +% \begin{markdown} +% +%#### Parsers Used for Fenced Code Blocks +% +% \end{markdown} % \begin{macrocode} local function captures_geq_length(s,i,a,b) return #a >= #b and i @@ -3226,7 +8103,12 @@ parsers.fencedline = function(char) end end % \end{macrocode} -% \paragraph{Parsers Used for Markdown Tags and Links} +% \par +% \begin{markdown} +% +%#### Parsers Used for Markdown Tags and Links +% +% \end{markdown} % \begin{macrocode} parsers.leader = parsers.space^-3 @@ -3293,7 +8175,12 @@ parsers.optionaltitle = parsers.spnl * parsers.title * parsers.spacechar^0 + Cc("") % \end{macrocode} -% \paragraph{Parsers Used for iA\,Writer Content Blocks} +% \par +% \begin{markdown} +% +%#### Parsers Used for iA\,Writer Content Blocks +% +% \end{markdown} % \begin{macrocode} parsers.contentblock_tail = parsers.optionaltitle @@ -3360,7 +8247,12 @@ parsers.localfilepath * Cs(parsers.alphanumeric^1) * Cc("localfile") % \end{macrocode} -% \paragraph{Parsers Used for Citations} +% \par +% \begin{markdown} +% +%#### Parsers Used for Citations +% +% \end{markdown} % \begin{macrocode} parsers.citation_name = Cs(parsers.dash^-1) * parsers.at * Cs(parsers.citation_chars @@ -3415,7 +8307,12 @@ parsers.citation_headless_body * (parsers.sp * parsers.semicolon * parsers.spnl * parsers.citation_body_chunk)^0 % \end{macrocode} -% \paragraph{Parsers Used for Footnotes} +% \par +% \begin{markdown} +% +%#### Parsers Used for Footnotes +% +% \end{markdown} % \begin{macrocode} local function strip_first_char(s) return s:sub(2) @@ -3424,7 +8321,12 @@ end parsers.RawNoteRef = #(parsers.lbracket * parsers.circumflex) * parsers.tag / strip_first_char % \end{macrocode} -% \paragraph{Parsers Used for \textsc{html}} +% \par +% \begin{markdown} +% +%#### Parsers Used for \textsc{html} +% +% \end{markdown} % \begin{macrocode} -- case-insensitive match (we assume s is lowercase). must be single byte encoding parsers.keyword_exact = function(s) @@ -3532,7 +8434,12 @@ parsers.inlinehtml = parsers.emptyelt_any + parsers.openelt_any + parsers.closeelt_any % \end{macrocode} -% \paragraph{Parsers Used for \textsc{html} entities} +% \par +% \begin{markdown} +% +%#### Parsers Used for \textsc{html} entities +% +% \end{markdown} % \begin{macrocode} parsers.hexentity = parsers.ampersand * parsers.hash * S("Xx") * C(parsers.hexdigit^1) * parsers.semicolon @@ -3541,14 +8448,24 @@ parsers.decentity = parsers.ampersand * parsers.hash parsers.tagentity = parsers.ampersand * C(parsers.alphanumeric^1) * parsers.semicolon % \end{macrocode} -% \paragraph{Helpers for References} +% \par +% \begin{markdown} +% +%#### Helpers for References +% +% \end{markdown} % \begin{macrocode} -- parse a reference definition: [foo]: /bar "title" parsers.define_reference_parser = parsers.leader * parsers.tag * parsers.colon * parsers.spacechar^0 * parsers.url * parsers.optionaltitle * parsers.blankline^1 % \end{macrocode} -% \paragraph{Inline Elements} +% \par +% \begin{markdown} +% +%#### Inline Elements +% +% \end{markdown} % \begin{macrocode} parsers.Inline = V("Inline") @@ -3560,7 +8477,12 @@ end parsers.urlchar = parsers.anyescaped - parsers.newline - parsers.more % \end{macrocode} -% \paragraph{Block Elements} +% \par +% \begin{markdown} +% +%#### Block Elements +% +% \end{markdown} % \begin{macrocode} parsers.Block = V("Block") @@ -3590,7 +8512,12 @@ parsers.lineof = function(c) + parsers.newline^-1 * parsers.eof)) end % \end{macrocode} -% \paragraph{Lists} +% \par +% \begin{markdown} +% +%#### Lists +% +% \end{markdown} % \begin{macrocode} parsers.defstartchar = S("~:") parsers.defstart = ( parsers.defstartchar * #parsers.spacing @@ -3606,7 +8533,12 @@ parsers.defstart = ( parsers.defstartchar * #parsers.spacing parsers.dlchunk = Cs(parsers.line * (parsers.indentedline - parsers.blankline)^0) % \end{macrocode} -% \paragraph{Headings} +% \par +% \begin{markdown} +% +%#### Headings +% +% \end{markdown} % \begin{macrocode} -- parse Atx heading start and return level parsers.HeadingStart = #parsers.hash * C(parsers.hash^-6) @@ -3619,12 +8551,15 @@ local function strip_atx_end(s) return s:gsub("[#%s]*\n$","") end % \end{macrocode} -% -% \subsubsection{Markdown Reader}\label{sec:markdownreader} +% \par +% \begin{markdown} +% +%### Markdown Reader +% \label{sec:markdownreader} % This section documents the \luam{reader} object, which implements the % routines for parsing the markdown input. The object corresponds to the % markdown reader object that was located in the -% \t`lunamark/reader/markdown.lua` file in the Lunamark Lua module. +% `lunamark/reader/markdown.lua` file in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section % \ref{sec:luainterface}), the \luam{reader} object is exported, so that the @@ -3634,40 +8569,54 @@ end % % The \luamdef{reader.new} method creates and returns a new \TeX{} reader % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) \t`options` and with a writer object \t`writer`. When -% \t`options` are unspecified, it is assumed that an empty table was passed to +% \ref{sec:luaoptions}) `options` and with a writer object `writer`. When +% `options` are unspecified, it is assumed that an empty table was passed to % the method. % % The objects produced by the \luam{reader.new} method expose instance methods % and variables of their own. As a convention, I will refer to these -% \meta{member}s as \t`reader->`\meta{member}. +% \meta{member}s as `reader->`\meta{member}. +% +% \end{markdown} % \begin{macrocode} M.reader = {} function M.reader.new(writer, options) local self = {} options = options or {} % \end{macrocode} +% \par +% \begin{markdown} +% +% Make the `options` table inherit from the \luam{defaultOptions} table. % -% Make the \t`options` table inherit from the \luam{defaultOptions} table. +% \end{markdown} % \begin{macrocode} setmetatable(options, { __index = function (_, key) return defaultOptions[key] end }) % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Top-Level Helper Functions} +%#### Top-Level Helper Functions % Define \luamdef{normalize_tag} as a function that normalizes a markdown % reference tag by lowercasing it, and by collapsing any adjacent whitespace % characters. +% +% \end{markdown} % \begin{macrocode} local function normalize_tag(tag) return unicode.utf8.lower( gsub(util.rope_to_string(tag), "[ \n\r\t]+", " ")) end % \end{macrocode} -% +% \par +% \begin{markdown} +% % Define \luamdef{expandtabs} either as an identity function, when the -% \Opt{preserveTabs} Lua inrerface option is \t`true`, or to a function that +% \Opt{preserveTabs} Lua inrerface option is `true`, or to a function that % expands tabs into spaces otherwise. +% +% \end{markdown} % \begin{macrocode} local expandtabs if options.preserveTabs then @@ -3682,14 +8631,23 @@ function M.reader.new(writer, options) end end % \end{macrocode} -% +% \par +% \begin{markdown} +% % The \luamdef{larsers} (as in ``local \luam{parsers}'') hash table stores -% \acro{peg} patterns that depend on the received \t`options`, which impedes +% \acro{peg} patterns that depend on the received `options`, which impedes % their reuse between different \luam{reader} objects. +% +% \end{markdown} % \begin{macrocode} local larsers = {} % \end{macrocode} -% \paragraph{Top-Level Parser Functions} +% \par +% \begin{markdown} +% +%#### Top-Level Parser Functions +% +% \end{markdown} % \begin{macrocode} local function create_parser(name, grammar) return function(str) @@ -3738,7 +8696,12 @@ function M.reader.new(writer, options) return larsers.inlines_nbsp end) % \end{macrocode} -% \paragraph{Parsers Used for Markdown Lists (local)} +% \par +% \begin{markdown} +% +%#### Parsers Used for Markdown Lists (local) +% +% \end{markdown} % \begin{macrocode} if options.hashEnumerators then larsers.dig = parsers.digit + parsers.hash @@ -3759,7 +8722,12 @@ function M.reader.new(writer, options) + parsers.space * parsers.space * C(larsers.dig^1 * parsers.period) * #parsers.spacing % \end{macrocode} -% \paragraph{Parsers Used for Blockquotes (local)} +% \par +% \begin{markdown} +% +%#### Parsers Used for Blockquotes (local) +% +% \end{markdown} % \begin{macrocode} -- strip off leading > and indents, and run through blocks larsers.blockquote_body = ((parsers.leader * parsers.more * parsers.space^-1)/"" @@ -3773,7 +8741,12 @@ function M.reader.new(writer, options) * (parsers.blankline^0 / "") end % \end{macrocode} -% \paragraph{Parsers Used for Citations (local)} +% \par +% \begin{markdown} +% +%#### Parsers Used for Citations (local) +% +% \end{markdown} % \begin{macrocode} larsers.citations = function(text_cites, raw_cites) local function normalize(str) @@ -3798,7 +8771,12 @@ function M.reader.new(writer, options) return writer.citations(text_cites, cites) end % \end{macrocode} -% \paragraph{Parsers Used for Footnotes (local)} +% \par +% \begin{markdown} +% +%#### Parsers Used for Footnotes (local) +% +% \end{markdown} % \begin{macrocode} local rawnotes = {} @@ -3830,7 +8808,12 @@ function M.reader.new(writer, options) * (parsers.tag / parse_inlines_no_inline_note) -- no notes inside notes / writer.note % \end{macrocode} -% \paragraph{Helpers for Links and References (local)} +% \par +% \begin{markdown} +% +%#### Helpers for Links and References (local) +% +% \end{markdown} % \begin{macrocode} -- List of references defined in the document local references @@ -3891,7 +8874,12 @@ function M.reader.new(writer, options) end end % \end{macrocode} -% \paragraph{Inline Elements (local)} +% \par +% \begin{markdown} +% +%#### Inline Elements (local) +% +% \end{markdown} % \begin{macrocode} larsers.Str = parsers.normalchar^1 / writer.string @@ -4053,7 +9041,12 @@ function M.reader.new(writer, options) + parsers.decentity / entities.dec_entity / writer.string + parsers.tagentity / entities.char_entity / writer.string % \end{macrocode} -% \paragraph{Block Elements (local)} +% \par +% \begin{markdown} +% +%#### Block Elements (local) +% +% \end{markdown} % \begin{macrocode} larsers.ContentBlock = parsers.leader * (parsers.localfilepath + parsers.onlineimageurl) @@ -4106,7 +9099,12 @@ function M.reader.new(writer, options) larsers.Plain = parsers.nonindentspace * Ct(parsers.Inline^1) / writer.plain % \end{macrocode} -% \paragraph{Lists (local)} +% \par +% \begin{markdown} +% +%#### Lists (local) +% +% \end{markdown} % \begin{macrocode} larsers.starter = parsers.bullet + larsers.enumerator @@ -4185,14 +9183,24 @@ function M.reader.new(writer, options) * -larsers.DefinitionListItemLoose * Cc(true)) ) / writer.definitionlist % \end{macrocode} -% \paragraph{Blank (local)} +% \par +% \begin{markdown} +% +%#### Blank (local) +% +% \end{markdown} % \begin{macrocode} larsers.Blank = parsers.blankline / "" + larsers.NoteBlock + larsers.Reference + (parsers.tightblocksep / "\n") % \end{macrocode} -% \paragraph{Headings (local)} +% \par +% \begin{markdown} +% +%#### Headings (local) +% +% \end{markdown} % \begin{macrocode} -- parse atx header larsers.AtxHeading = Cg(parsers.HeadingStart,"level") @@ -4210,7 +9218,12 @@ function M.reader.new(writer, options) larsers.Heading = larsers.AtxHeading + larsers.SetextHeading % \end{macrocode} -% \paragraph{Syntax Specification} +% \par +% \begin{markdown} +% +%#### Syntax Specification +% +% \end{markdown} % \begin{macrocode} local syntax = { "Blocks", @@ -4353,19 +9366,25 @@ function M.reader.new(writer, options) inlines_nbsp_t.Space = larsers.NonbreakingSpace larsers.inlines_nbsp = Ct(inlines_nbsp_t) % \end{macrocode} +% \par +% \begin{markdown} % -% \paragraph{Exported Conversion Function} +%#### Exported Conversion Function % Define \luamdef{reader->convert} as a function that converts markdown string -% \t`input` into a plain \TeX{} output and returns it. Note that the converter +% `input` into a plain \TeX{} output and returns it. Note that the converter % assumes that the input has \acro{unix} line endings. +% +% \end{markdown} % \begin{macrocode} function self.convert(input) references = {} % \end{macrocode} +% \begin{markdown} % When determining the name of the cache file, create salt for the hashing % function out of the package version and the passed options recognized by the % Lua interface (see Section \ref{sec:luaoptions}). The \Opt{cacheDir} option % is disregarded. +% \end{markdown} % \begin{macrocode} local opt_string = {} for k,_ in pairs(defaultOptions) do @@ -4377,8 +9396,10 @@ function M.reader.new(writer, options) table.sort(opt_string) local salt = table.concat(opt_string, ",") .. "," .. metadata.version % \end{macrocode} +% \begin{markdown} % Produce the cache file, transform its filename via the \luam{writer->pack} % method, and return the result. +% \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 @@ -4388,11 +9409,16 @@ function M.reader.new(writer, options) return self end % \end{macrocode} -% \subsubsection{Conversion from Markdown to Plain \TeX{}} +% \par +% \begin{markdown} +% +%### Conversion from Markdown to Plain \TeX{} % The \luam{new} method returns the \luam{reader->convert} function of a reader % object associated with the Lua interface options (see Section -% \ref{sec:luaoptions}) \t`options` and with a writer object associated with -% \t`options`. +% \ref{sec:luaoptions}) `options` and with a writer object associated with +% `options`. +% +% \end{markdown} % \begin{macrocode} function M.new(options) local writer = M.writer.new(options) @@ -4402,17 +9428,84 @@ end return M % \end{macrocode} -% % \iffalse %</lua> +%<*lua-cli> +% \fi +% \par +% \begin{markdown} +% +%### Command-Line Implementation +% \label{sec:lua-cli-implementation} +% The command-line implementation provides the actual conversion routine for +% the command-line interface described in Section~\ref{sec:lua-cli-interface}. +% +% \end{markdown} +% \begin{macrocode} + +local input +if input_filename then + local input_file = io.open(input_filename, "r") + input = assert(input_file:read("*a")) + input_file:close() +else + input = assert(io.read("*a")) +end + +% \end{macrocode} +% \begin{markdown} +% First, ensure that the `options.cacheDir` directory exists. +% \end{markdown} +% \begin{macrocode} +local lfs = require("lfs") +if options.cacheDir and not lfs.isdir(options.cacheDir) then + assert(lfs.mkdir(options["cacheDir"])) +end + +local kpse = require("kpse") +kpse.set_program_name("luatex") +local md = require("markdown") +% \end{macrocode} +% \begin{markdown} +% Since we are loading the rest of the Lua implementation dynamically, +% check that both the `markdown` module and the command line implementation +% are the same version. +% \end{markdown} +% \begin{macrocode} +if metadata.version ~= md.metadata.version then + warn("markdown-cli.lua " .. metadata.version .. " used with " .. + "markdown.lua " .. md.metadata.version .. ".") +end +local convert = md.new(options) +local output = convert(input:gsub("\r\n?", "\n")) + +if output_filename then + local output_file = io.open(output_filename, "w") + assert(output_file:write(output)) + assert(output_file:close()) +else + assert(io.write(output)) +end +% \end{macrocode} +% \iffalse +%</lua-cli> %<*tex> -% \fi\subsection{Plain \TeX{} Implementation}\label{sec:teximplementation} +% \fi +% \par +% \begin{markdown} +% +% Plain \TeX{} Implementation +%---------------------------- +% \label{sec:teximplementation} % The plain \TeX{} implementation provides macros for the interfacing between % \TeX{} and Lua and for the buffering of input text. These macros are then % used to implement the macros for the conversion from markdown to plain \TeX{} % exposed by the plain \TeX{} interface (see Section \ref{sec:texinterface}). % -% \subsubsection{Logging Facilities}\label{sec:texinterfacelogging} +%### Logging Facilities +% \label{sec:texinterfacelogging} +% +% \end{markdown} % \begin{macrocode} \def\markdownInfo#1{% \immediate\write-1{(l.\the\inputlineno) markdown.tex info: #1.}}% @@ -4422,16 +9515,20 @@ return M \errhelp{#2.}% \errmessage{(l.\the\inputlineno) markdown.tex error: #1}}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Token Renderer Prototypes} +%### Token Renderer Prototypes % The following definitions should be considered placeholder. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererInterblockSeparatorPrototype{\par}% \def\markdownRendererLineBreakPrototype{\hfil\break}% \let\markdownRendererEllipsisPrototype\dots \def\markdownRendererNbspPrototype{~}% -\def\markdownRendererLeftBracePrototype{\char`{}% -\def\markdownRendererRightBracePrototype{\char`}}% +\def\markdownRendererLeftBracePrototype{\char`\{}% +\def\markdownRendererRightBracePrototype{\char`\}}% \def\markdownRendererDollarSignPrototype{\char`$}% \def\markdownRendererPercentSignPrototype{\char`\%}% \def\markdownRendererAmpersandPrototype{\char`&}% @@ -4476,7 +9573,7 @@ return M \def\markdownRendererBlockQuoteBeginPrototype{\par\begingroup\it}% \def\markdownRendererBlockQuoteEndPrototype{\endgroup\par}% \def\markdownRendererInputVerbatimPrototype#1{% - \par{\tt\input"#1"\relax}\par}% + \par{\tt\input"#1"\relax{}}\par}% \def\markdownRendererInputFencedCodePrototype#1#2{% \markdownRendererInputVerbatimPrototype{#1}}% \def\markdownRendererHeadingOnePrototype#1{#1}% @@ -4490,11 +9587,15 @@ return M \def\markdownRendererCitePrototype#1{}% \def\markdownRendererTextCitePrototype#1{}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Lua Snippets} +%### Lua Snippets % The \mdef{markdownLuaOptions} macro expands to a Lua table that % contains the plain \TeX{} options (see Section \ref{sec:texoptions}) in a % format recognized by Lua (see Section \ref{sec:luaoptions}). +% +% \end{markdown} % \begin{macrocode} \def\markdownLuaOptions{{% \ifx\markdownOptionBlankBeforeBlockquote\undefined\else @@ -4547,7 +9648,6 @@ return M \ifx\markdownOptionInlineFootnotes\undefined\else inlineFootnotes = \markdownOptionInlineFootnotes, \fi - outputDir = "\markdownOptionOutputDir", \ifx\markdownOptionPreserveTabs\undefined\else preserveTabs = \markdownOptionPreserveTabs, \fi @@ -4565,146 +9665,224 @@ return M \fi} }% % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownPrepare} macro contains the Lua code that is executed prior % to any conversion from markdown to plain \TeX{}. It exposes the % \luam{convert} function for the use by any further Lua code. +% +% \end{markdown} % \begin{macrocode} \def\markdownPrepare{% % \end{macrocode} +% \begin{markdown} % First, ensure that the \m{markdownOptionCacheDir} directory exists. +% \end{markdown} % \begin{macrocode} local lfs = require("lfs") local cacheDir = "\markdownOptionCacheDir" -if lfs.isdir(cacheDir) == true then else +if not lfs.isdir(cacheDir) then assert(lfs.mkdir(cacheDir)) end % \end{macrocode} -% Next, load the \t`markdown` module and create a converter function using +% \begin{markdown} +% Next, load the `markdown` module and create a converter function using % the plain \TeX{} options, which were serialized to a Lua table via the % \m{markdownLuaOptions} macro. +% \end{markdown} % \begin{macrocode} local md = require("markdown") local convert = md.new(\markdownLuaOptions) }% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Buffering Markdown Input} +%### Buffering Markdown Input +% \label{sec:buffering} % The macros \mdef{markdownInputFileStream} and \mdef{markdownOutputFileStream} % contain the number of the input and output file streams that will be used for % the IO operations of the package. +% +% \end{markdown} % \begin{macrocode} \csname newread\endcsname\markdownInputFileStream \csname newwrite\endcsname\markdownOutputFileStream % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownReadAndConvertTab} macro contains the tab character literal. +% +% \end{markdown} % \begin{macrocode} \begingroup \catcode`\^^I=12% \gdef\markdownReadAndConvertTab{^^I}% \endgroup % \end{macrocode} +% \par +% \begin{markdown} % % The \m{markdownReadAndConvert} macro is largely a rewrite of the % \Hologo{LaTeX2e} \m{filecontents} macro to plain \TeX{}. +% +% \end{markdown} % \begin{macrocode} \begingroup % \end{macrocode} -% Make the newline and tab characters active and swap the character codes of the -% backslash symbol (\t`\textbackslash`) and the pipe symbol (\t`|`), so that -% we can use the backslash as an ordinary character inside the macro definition. +% \begin{markdown} +% Make the newline and tab characters active and swap the character codes of +% the backslash symbol (`\`) and the pipe symbol (`|`), so that we can use the +% 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 +% \m{markdownOptionStripPercentSigns} is `true`. +% \end{markdown} % \begin{macrocode} \catcode`\^^M=13% \catcode`\^^I=13% \catcode`|=0% \catcode`\\=12% - |gdef|markdownReadAndConvert#1#2{% - |begingroup% + |catcode`@=14% + |catcode`|%=12@ + |gdef|markdownReadAndConvert#1#2{@ + |begingroup@ % \end{macrocode} +% \begin{markdown} % Open the \m{markdownOptionInputTempFileName} file for writing. +% \end{markdown} % \begin{macrocode} - |immediate|openout|markdownOutputFileStream% - |markdownOptionInputTempFileName% - |markdownInfo{Buffering markdown input into the temporary % - input file "|markdownOptionInputTempFileName" and scanning % - for the closing token sequence "#1"}% + |immediate|openout|markdownOutputFileStream@ + |markdownOptionInputTempFileName@ + |markdownInfo{Buffering markdown input into the temporary @ + input file "|markdownOptionInputTempFileName" and scanning @ + for the closing token sequence "#1"}@ % \end{macrocode} +% \begin{markdown} % Locally change the category of the special plain \TeX{} characters to -% \emph{other} in order to prevent unwanted interpretation of the input. -% Change also the category of the space character, so that we can retrieve it +% *other* in order to prevent unwanted interpretation of the input. Change +% also the category of the space character, so that we can retrieve it % unaltered. -% \begin{macrocode} - |def|do##1{|catcode`##1=12}|dospecials% - |catcode`| =12% - |markdownMakeOther% -% \end{macrocode} +% \end{markdown} +% \begin{macrocode} + |def|do##1{|catcode`##1=12}|dospecials@ + |catcode`| =12@ + |markdownMakeOther@ +% \end{macrocode} +% \begin{markdown} +% The \mdef{markdownReadAndConvertStripPercentSigns} macro will process the +% individual lines of output, stipping away leading percent signs (`%`) when +% \m{markdownOptionStripPercentSigns} is `true`. +% 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. +% \end{markdown} +% \begin{macrocode} + |def|markdownReadAndConvertStripPercentSign##1{@ + |markdownIfOption{StripPercentSigns}@ + |if##1%@ + |expandafter|expandafter|expandafter@ + |markdownReadAndConvertProcessLine@ + |else@ + |expandafter|expandafter|expandafter@ + |markdownReadAndConvertProcessLine@ + |expandafter|expandafter|expandafter##1@ + |fi@ + |else@ + |expandafter@ + |markdownReadAndConvertProcessLine@ + |expandafter##1@ + |fi}@ +% \end{macrocode} +% \begin{markdown} % The \mdef{markdownReadAndConvertProcessLine} macro will process the individual -% lines of output. Note the use of the comments to ensure that the entire macro -% is at a single line and therefore no (active) newline symbols are produced. +% lines of output. +% 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. +% \end{markdown} % \begin{macrocode} - |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{% + |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{@ % \end{macrocode} +% \begin{markdown} % When the ending token sequence does not appear in the line, store the line in % the \m{markdownOptionInputTempFileName} file. +% \end{markdown} % \begin{macrocode} - |ifx|relax##3|relax% - |immediate|write|markdownOutputFileStream{##1}% - |else% + |ifx|relax##3|relax@ + |immediate|write|markdownOutputFileStream{##1}@ + |else@ % \end{macrocode} +% \begin{markdown} % When the ending token sequence appears in the line, make the next newline % character close the \m{markdownOptionInputTempFileName} file, return the % character categories back to the former state, convert the % \m{markdownOptionInputTempFileName} file from markdown to plain \TeX{}, % \m{input} the result of the conversion, and expand the ending control % sequence. +% \end{markdown} % \begin{macrocode} - |def^^M{% - |markdownInfo{The ending token sequence was found}% - |immediate|closeout|markdownOutputFileStream% - |endgroup% - |markdownInput|markdownOptionInputTempFileName% - #2}% - |fi% + |def^^M{@ + |markdownInfo{The ending token sequence was found}@ + |immediate|closeout|markdownOutputFileStream@ + |endgroup@ + |markdownInput|markdownOptionInputTempFileName@ + #2}@ + |fi@ % \end{macrocode} +% \begin{markdown} % Repeat with the next line. +% \end{markdown} % \begin{macrocode} - ^^M}% + ^^M}@ % \end{macrocode} +% \begin{markdown} % Make the tab character active at expansion time and make it expand to a % literal tab character. +% \end{markdown} % \begin{macrocode} - |catcode`|^^I=13% - |def^^I{|markdownReadAndConvertTab}% + |catcode`|^^I=13@ + |def^^I{|markdownReadAndConvertTab}@ % \end{macrocode} +% \begin{markdown} % Make the newline character active at expansion time and make it consume the % rest of the line on expansion. Throw away the rest of the first line and % pass the second line to the \m{markdownReadAndConvertProcessLine} macro. +% \end{markdown} % \begin{macrocode} - |catcode`|^^M=13% - |def^^M##1^^M{% - |def^^M####1^^M{% - |markdownReadAndConvertProcessLine####1#1#1|relax}% - ^^M}% - ^^M}% + |catcode`|^^M=13@ + |def^^M##1^^M{@ + |def^^M####1^^M{@ + |markdownReadAndConvertStripPercentSign####1#1#1|relax}@ + ^^M}@ + ^^M}@ % \end{macrocode} +% \begin{markdown} % Reset the character categories back to the former state. +% \end{markdown} % \begin{macrocode} |endgroup % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Lua Shell Escape Bridge}\label{sec:luabridge} +%### Lua Shell Escape Bridge +% \label{sec:luabridge} % The following \TeX{} code is intended for \TeX{} engines that do not provide % direct access to Lua, but expose the shell of the operating system. This -% corresponds to the \m{markdownMode} values of \t`0` and \t`1`. +% corresponds to the \m{markdownMode} values of `0` and `1`. % % The \m{markdownLuaExecute} macro defined here and in Section % \ref{sec:directlua} are meant to be indistinguishable to the remaining code. % % The package assumes that although the user is not using the Lua\TeX{} engine, % their TeX distribution contains it, and uses shell access to produce and -% execute Lua scripts using the \TeX{}Lua interpreter (see -% \cite[Section~3.1.1]{luatex17}). +% execute Lua scripts using the \TeX{}Lua interpreter~[@luatex17, Section +% 3.1.1]. +% +% \end{markdown} % \begin{macrocode} \ifnum\markdownMode<2\relax \ifnum\markdownMode=0\relax @@ -4713,17 +9891,21 @@ local convert = md.new(\markdownLuaOptions) \markdownInfo{Using mode 1: Shell escape via os.execute}% \fi % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownExecuteShellEscape} macro contains the numeric value indicating -% whether the shell access is enabled (\t`1`), disabled (\t`0`), or restricted -% (\t`2`). -% +% whether the shell access is enabled (`1`), disabled (`0`), or restricted +% (`2`). +% % Inherit the value of the the \m{pdfshellescape} (Lua\TeX{}, \Hologo{pdfTeX}) % or the \m{shellescape} (\Hologo{XeTeX}) commands. If neither of these % commands is defined and Lua is available, attempt to access the % \luam{status.shell_escape} configuration item. % % If you cannot detect, whether the shell access is enabled, act as if it were. +% +% \end{markdown} % \begin{macrocode} \ifx\pdfshellescape\undefined \ifx\shellescape\undefined @@ -4740,10 +9922,14 @@ local convert = md.new(\markdownLuaOptions) \let\markdownExecuteShellEscape\pdfshellescape \fi % \end{macrocode} +% \par +% \begin{markdown} % % 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 \luam{os.execute} method otherwise. +% +% \end{markdown} % \begin{macrocode} \ifnum\markdownMode=0\relax \def\markdownExecuteDirect#1{\immediate\write18{#1}}% @@ -4752,11 +9938,15 @@ local convert = md.new(\markdownLuaOptions) \directlua{os.execute("\luaescapestring{#1}")}}% \fi % \end{macrocode} +% \par +% \begin{markdown} % % The \mdef{markdownExecute} macro is a wrapper on top of % \m{markdownExecuteDirect} that checks the value of % \m{markdownExecuteShellEscape} and prints an error message if the shell is % inaccessible. +% +% \end{markdown} % \begin{macrocode} \def\markdownExecute#1{% \ifnum\markdownExecuteShellEscape=1\relax @@ -4767,24 +9957,32 @@ local convert = md.new(\markdownLuaOptions) or set shell_escape=t in the texmf.cnf file}% \fi}% % \end{macrocode} +% \par +% \begin{markdown} % % 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 \luam{print} function in the same manner it % would use the \luam{tex.print} method. +% +% \end{markdown} % \begin{macrocode} \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{% % \end{macrocode} +% \begin{markdown} % Create the file \m{markdownOptionHelperScriptFileName} 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} % \begin{macrocode} |immediate|openout|markdownOutputFileStream=% |markdownOptionHelperScriptFileName @@ -4792,13 +9990,15 @@ local convert = md.new(\markdownLuaOptions) "|markdownOptionHelperScriptFileName"}% |immediate|write|markdownOutputFileStream{% local ran_ok, error = pcall(function() - local kpse = require('kpse') - kpse.set_program_name('luatex') + local kpse = require("kpse") + kpse.set_program_name("luatex") #1 end) % \end{macrocode} +% \begin{markdown} % If there was an error, use the file \m{markdownOptionErrorTempFileName} to % store the error message. +% \end{markdown} % \begin{macrocode} if not ran_ok then local file = io.open("% @@ -4815,9 +10015,11 @@ local convert = md.new(\markdownLuaOptions) end}% |immediate|closeout|markdownOutputFileStream % \end{macrocode} +% \begin{markdown} % Execute the generated \m{markdownOptionHelperScriptFileName} Lua script using % the \TeX{}Lua binary and store the output in the % \m{markdownOptionOutputTempFileName} file. +% \end{markdown} % \begin{macrocode} |markdownInfo{Executing a helper Lua script from the file "|markdownOptionHelperScriptFileName" and storing the result in the @@ -4827,93 +10029,130 @@ local convert = md.new(\markdownLuaOptions) "|markdownOptionOutputDir /|markdownOptionOutputTempFileName"}% % \end{macrocode} +% \begin{markdown} % \m{input} the generated \m{markdownOptionOutputTempFileName} file. +% \end{markdown} % \begin{macrocode} |input|markdownOptionOutputTempFileName|relax}% |endgroup % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Direct Lua Access}\label{sec:directlua} +%### Direct Lua Access +% \label{sec:directlua} % The following \TeX{} code is intended for \TeX{} engines that provide % direct access to Lua (Lua\TeX{}). The macro \m{markdownLuaExecute} defined % here and in Section \ref{sec:luabridge} are meant to be indistinguishable to -% the remaining code. This corresponds to the \m{markdownMode} value of \t`2`. +% the remaining code. This corresponds to the \m{markdownMode} value of `2`. +% +% \end{markdown} % \begin{macrocode} \else \markdownInfo{Using mode 2: Direct Lua access}% % \end{macrocode} +% \par +% \begin{markdown} +% % The direct Lua access version of the \m{markdownLuaExecute} macro is defined % in terms of the \m{directlua} primitive. The \luam{print} function is set as % an alias to the \m{tex.print} method in order to mimic the behaviour of the % \m{markdownLuaExecute} definition from Section \ref{sec:luabridge}, +% +% \end{markdown} % \begin{macrocode} \def\markdownLuaExecute#1{\directlua{local print = tex.print #1}}% \fi % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Typesetting Markdown} +%### Typesetting Markdown % The \m{markdownInput} macro uses an implementation of the % \m{markdownLuaExecute} macro to convert the contents of the file whose % filename it has received as its single argument from markdown to plain % \TeX{}. +% +% \end{markdown} % \begin{macrocode} \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|markdownInput#1{% |markdownInfo{Including markdown document "#1"}% % \end{macrocode} -% Attempt to open the markdown document to record it in the \t`.log` and -% \t`.fls` files. This allows external programs such as \LaTeX Mk to track +% \begin{markdown} +% Attempt to open the markdown document to record it in the `.log` and +% `.fls` files. This allows external programs such as \LaTeX Mk to track % changes to the markdown document. +% \end{markdown} % \begin{macrocode} |openin|markdownInputFileStream#1 |closein|markdownInputFileStream |markdownLuaExecute{% |markdownPrepare - local input = assert(io.open("#1","r")):read("*a") + local input = assert(io.open("#1", "r"):read("*a")) % \end{macrocode} +% \begin{markdown} % Since the Lua converter expects \acro{unix} line endings, normalize the % input. +% \end{markdown} % \begin{macrocode} print(convert(input:gsub("\r\n?", "\n")))}}% |endgroup % \end{macrocode} -% % \iffalse %</tex> %<*latex> -% \fi\subsection{\LaTeX{} Implementation}\label{sec:lateximplementation} +% \fi +% \par +% \begin{markdown} +% +% \LaTeX{} Implementation +%------------------------ +% \label{sec:lateximplementation} % The \LaTeX{} implemenation makes use of the fact that, apart from some subtle -% differences, \LaTeX{} implements the majority of the plain \TeX{} format -% (see \cite[Section~9]{latex17}). As a consequence, we can directly reuse the +% differences, \LaTeX{} implements the majority of the plain \TeX{} +% format~[@latex17, Section 9]. As a consequence, we can directly reuse the % existing plain \TeX{} implementation. +% +% \end{markdown} % \begin{macrocode} \input markdown \def\markdownVersionSpace{ }% \ProvidesPackage{markdown}[\markdownLastModified\markdownVersionSpace v% \markdownVersion\markdownVersionSpace markdown renderer]% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Logging Facilities} +%### Logging Facilities % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see % Section \ref{sec:texinterfacelogging}) to use the \LaTeX{} \m{PackageInfo}, % \m{PackageWarning}, and \m{PackageError} macros. +% +% \end{markdown} % \begin{macrocode} \renewcommand\markdownInfo[1]{\PackageInfo{markdown}{#1}}% \renewcommand\markdownWarning[1]{\PackageWarning{markdown}{#1}}% \renewcommand\markdownError[2]{\PackageError{markdown}{#1}{#2.}}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Typesetting Markdown} +%### Typesetting Markdown % The \mdef{markdownInputPlainTeX} macro is used to store the original plain % \TeX{} implementation of the \m{markdownInput} macro. The \m{markdownInput} % is then redefined to accept an optional argument with options recognized by % the \LaTeX{} interface (see Section \ref{sec:latexoptions}). +% +% \end{markdown} % \begin{macrocode} \let\markdownInputPlainTeX\markdownInput \renewcommand\markdownInput[2][]{% @@ -4922,9 +10161,13 @@ local convert = md.new(\markdownLuaOptions) \markdownInputPlainTeX{#2}% \endgroup}% % \end{macrocode} +% \par +% \begin{markdown} +% +% The \envm{markdown}, and \envm{markdown*} \LaTeX{} environments are +% implemented using the \m{markdownReadAndConvert} macro. % -% The \env{markdown}, and \env{markdown*} \LaTeX{} environments are implemented -% using the \m{markdownReadAndConvert} macro. +% \end{markdown} % \begin{macrocode} \renewenvironment{markdown}{% \markdownReadAndConvert@markdown{}}\relax @@ -4933,11 +10176,13 @@ local convert = md.new(\markdownLuaOptions) \markdownReadAndConvert@markdown*}\relax \begingroup % \end{macrocode} +% \begin{markdown} % Locally swap the category code of the backslash symbol with the pipe symbol, -% and of the left (\t`\{`) and right brace (\t`\}`) with the less-than (\t`<`) -% and greater-than (\t`>`) signs. This is required in order that all the +% and of the left (`{`) and right brace (`}`) with the less-than (`<`) +% and greater-than (`>`) signs. This is required in order that all the % special symbols that appear in the first argument of the -% \t`markdownReadAndConvert` macro have the category code \emph{other}. +% `markdownReadAndConvert` macro have the category code *other*. +% \end{markdown} % \begin{macrocode} \catcode`\|=0\catcode`\<=1\catcode`\>=2% \catcode`\\=12|catcode`|{=12|catcode`|}=12% @@ -4946,16 +10191,25 @@ local convert = md.new(\markdownLuaOptions) <|end<markdown#1>>>% |endgroup % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Options} +%### Options % The supplied package options are processed using the \m{markdownSetup} macro. +% +% \end{markdown} % \begin{macrocode} \DeclareOption*{% \expandafter\markdownSetup\expandafter{\CurrentOption}}% \ProcessOptions\relax % \end{macrocode} -% After processing the options, activate the \t`renderers` and -% \t`rendererPrototypes` keys. +% \par +% \begin{markdown} +% +% After processing the options, activate the `renderers` and +% `rendererPrototypes` keys. +% +% \end{markdown} % \begin{macrocode} \define@key{markdownOptions}{renderers}{% \setkeys{markdownRenderers}{#1}% @@ -4964,15 +10218,19 @@ local convert = md.new(\markdownLuaOptions) \setkeys{markdownRendererPrototypes}{#1}% \def\KV@prefix{KV@markdownOptions@}}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Token Renderer Prototypes} +%### Token Renderer Prototypes % The following configuration should be considered placeholder. % -% If the \m{markdownOptionTightLists} macro expands to \t`false`, do not load +% If the \m{markdownOptionTightLists} macro expands to `false`, do not load % the \pkg{paralist} package. This is necessary for \Hologo{LaTeX2e} document % classes that do not play nice with \pkg{paralist}, such as \pkg{beamer}. % If the \m{markdownOptionTightLists} is undefined and the \pkg{beamer} % document class is in use, then do not load the \pkg{paralist} package either. +% +% \end{markdown} % \begin{macrocode} \ifx\markdownOptionTightLists\undefined \@ifclassloaded{beamer}{}{ @@ -4982,10 +10240,15 @@ local convert = md.new(\markdownLuaOptions) \RequirePackage{paralist}} \fi % \end{macrocode} +% \par +% \begin{markdown} +% % If we loaded the \pkg{paralist} package, define the respective renderer % prototypes to make use of the capabilities of the package. Otherwise, % define the renderer prototypes to fall back on the corresponding renderers % for the non-tight lists. +% +% \end{markdown} % \begin{macrocode} \@ifpackageloaded{paralist}{ \markdownSetup{rendererPrototypes={ @@ -5014,8 +10277,6 @@ local convert = md.new(\markdownLuaOptions) tilde = {\textasciitilde}, pipe = {\textbar}, codeSpan = {\texttt{#1}}, - link = {#1\footnote{\ifx\empty#4\empty\else#4: - \fi\texttt<\url{#3}\texttt>}}, contentBlock = {% \ifthenelse{\equal{#1}{csv}}{% \begin{table}% @@ -5056,18 +10317,28 @@ local convert = md.new(\markdownLuaOptions) \ifx\relax#2\relax \VerbatimInput{#1}% \else - \ifx\minted@jobname\undefined + \ifx\minted@code\undefined \ifx\lst@version\undefined \markdownRendererInputFencedCode{#1}{}% % \end{macrocode} +% \par +% \begin{markdown} +% % When the \pkg{listings} package is loaded, use it for syntax highlighting. +% +% \end{markdown} % \begin{macrocode} \else \lstinputlisting[language=#2]{#1}% \fi % \end{macrocode} +% \par +% \begin{markdown} +% % When the \pkg{minted} package is loaded, use it for syntax highlighting. % The \pkg{minted} package is preferred over \pkg{listings}. +% +% \end{markdown} % \begin{macrocode} \else \inputminted{#2}{#1}% @@ -5076,8 +10347,12 @@ local convert = md.new(\markdownLuaOptions) horizontalRule = {\noindent\rule[0.5ex]{\linewidth}{1pt}}, footnote = {\footnote{#1}}}} % \end{macrocode} +% \par +% \begin{markdown} % % Support the nesting of strong emphasis. +% +% \end{markdown} % \begin{macrocode} \newif\ifmarkdownLATEXStrongEmphasisNested \markdownLATEXStrongEmphasisNestedfalse @@ -5093,31 +10368,39 @@ local convert = md.new(\markdownLuaOptions) \markdownLATEXStrongEmphasisNestedfalse \fi}}} % \end{macrocode} +% \par +% \begin{markdown} % % Support \LaTeX{} document classes that do not provide chapters. +% +% \end{markdown} % \begin{macrocode} \ifx\chapter\undefined \markdownSetup{rendererPrototypes = { headingOne = {\section{#1}}, headingTwo = {\subsection{#1}}, headingThree = {\subsubsection{#1}}, - headingFour = {\paragraph{#1}}, - headingFive = {\subparagraph{#1}}}} + headingFour = {\paragraph{#1}\leavevmode}, + headingFive = {\subparagraph{#1}\leavevmode}}} \else \markdownSetup{rendererPrototypes = { headingOne = {\chapter{#1}}, headingTwo = {\section{#1}}, headingThree = {\subsection{#1}}, headingFour = {\subsubsection{#1}}, - headingFive = {\paragraph{#1}}, - headingSix = {\subparagraph{#1}}}} + headingFive = {\paragraph{#1}\leavevmode}, + headingSix = {\subparagraph{#1}\leavevmode}}} \fi % \end{macrocode} +% \par +% \begin{markdown} % % There is a basic implementation for citations that uses the \LaTeX{} \m{cite} % macro. There is also a more advanced implementation that uses the Bib\LaTeX{} % \m{autocites} and \m{textcites} macros. This implementation will be used, when % Bib\LaTeX{} is loaded. +% +% \end{markdown} % \begin{macrocode} \newcount\markdownLaTeXCitationsCounter @@ -5168,12 +10451,35 @@ local convert = md.new(\markdownLuaOptions) \expandafter{\expandafter}% \fi}}} % \end{macrocode} +% \par +% \begin{markdown} +% +% Before consuming the parameters for the hyperlink renderer, we change the +% category code of the hash sign (`#`) to other, so that it cannot be +% mistaken for a parameter character. After the hyperlink has been typeset, +% we restore the original catcode. +% +% \end{markdown} +% \begin{macrocode} +\def\markdownRendererLinkPrototype{% + \begingroup + \catcode`\#=12 + \def\next##1##2##3##4{% + ##1\footnote{% + \ifx\empty##4\empty\else##4: \fi\texttt<\url{##3}\texttt>}% + \endgroup}% + \next} +% \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Miscellanea} +%### Miscellanea % When buffering user input, we should disable the bytes with the high bit set, % since these are made active by the \pkg{inputenc} package. We will do this by % redefining the \m{markdownMakeOther} macro accordingly. The code is courtesy % of Scott Pakin, the creator of the \pkg{filecontents} package. +% +% \end{markdown} % \begin{macrocode} \newcommand\markdownMakeOther{% \count0=128\relax @@ -5182,28 +10488,38 @@ local convert = md.new(\markdownLuaOptions) \advance\count0 by 1\relax \ifnum\count0<256\repeat}% % \end{macrocode} -% % \iffalse %</latex> %<*context> -% \fi\subsection{\Hologo{ConTeXt} Implementation} +% \fi +% \par +% \begin{markdown} +% +% \Hologo{ConTeXt} Implementation +%-------------------------------- % \label{sec:contextimplementation} % The \Hologo{ConTeXt} implementation makes use of the fact that, apart from % some subtle differences, the Mark II and Mark IV \Hologo{ConTeXt} formats -% \emph{seem} to implement (the documentation is scarce) the majority of the +% *seem* to implement (the documentation is scarce) the majority of the % plain \TeX{} format required by the plain \TeX{} implementation. As a % consequence, we can directly reuse the existing plain \TeX{} implementation % after supplying the missing plain \TeX{} macros. +% +% \end{markdown} % \begin{macrocode} \def\dospecials{\do\ \do\\\do\{\do\}\do\$\do\&% \do\#\do\^\do\_\do\%\do\~}% \input markdown % \end{macrocode} +% \par +% \begin{markdown} % % When buffering user input, we should disable the bytes with the high bit set, % since these are made active by the \m{enableregime} macro. We will do this % by redefining the \m{markdownMakeOther} macro accordingly. The code is % courtesy of Scott Pakin, the creator of the \pkg{filecontents} LaTeX package. +% +% \end{markdown} % \begin{macrocode} \def\markdownMakeOther{% \count0=128\relax @@ -5212,31 +10528,46 @@ local convert = md.new(\markdownLuaOptions) \advance\count0 by 1\relax \ifnum\count0<256\repeat % \end{macrocode} -% On top of that, make the pipe character (\t`|`) inactive during the scanning. +% \par +% \begin{markdown} +% +% On top of that, make the pipe character (`|`) inactive during the scanning. % This is necessary, since the character is active in \Hologo{ConTeXt}. +% +% \end{markdown} % \begin{macrocode} \catcode`|=12}% % \end{macrocode} -% -% \subsubsection{Logging Facilities} +% \par +% \begin{markdown} +% +%### Logging Facilities % The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros (see % Section \ref{sec:texinterfacelogging}) to use the \Hologo{ConTeXt} % \m{writestatus} macro. +% +% \end{markdown} % \begin{macrocode} \def\markdownInfo#1{\writestatus{markdown}{#1.}}% \def\markdownWarning#1{\writestatus{markdown\space warn}{#1.}}% % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Typesetting Markdown} +%### Typesetting Markdown % The \m{startmarkdown} and \m{stopmarkdown} macros are implemented using the % \m{markdownReadAndConvert} macro. +% +% \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 \t`markdownReadAndConvert` macro have the category code -% \emph{other}. +% first argument of the `markdownReadAndConvert` macro have the category code +% *other*. +% \end{markdown} % \begin{macrocode} \catcode`\|=0% \catcode`\\=12% @@ -5245,9 +10576,13 @@ local convert = md.new(\markdownLuaOptions) {|stopmarkdown}}% |endgroup % \end{macrocode} +% \par +% \begin{markdown} % -% \subsubsection{Token Renderer Prototypes} +%### Token Renderer Prototypes % The following configuration should be considered placeholder. +% +% \end{markdown} % \begin{macrocode} \def\markdownRendererLineBreakPrototype{\blank}% \def\markdownRendererLeftBracePrototype{\textbraceleft}% @@ -5326,15 +10661,17 @@ local convert = md.new(\markdownLuaOptions) \typefile{#1}% \else % \end{macrocode} -% +% \par +% \begin{markdown} +% % The code fence infostring is used as a name from the \Hologo{ConTeXt} % \m{definetyping} macro. This allows the user to set up code highlighting % mapping as follows: -% \begin{Verbatim} +% ````` tex % % Map the `TEX` syntax highlighter to the `latex` infostring. % \definetyping [latex] % \setuptyping [latex] [option=TEX] -% +% % \starttext % \startmarkdown % ~~~ latex @@ -5345,7 +10682,9 @@ local convert = md.new(\markdownLuaOptions) % ~~~ % \stopmarkdown % \stoptext -% \end{Verbatim} +% ````````` +% +% \end{markdown} % \begin{macrocode} \typefile[#2][]{#1}% \fi}% @@ -5360,7 +10699,6 @@ local convert = md.new(\markdownLuaOptions) \def\markdownRendererFootnotePrototype#1{\footnote{#1}}% \stopmodule\protect % \end{macrocode} -% % \iffalse %</context> % \fi |