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