diff options
Diffstat (limited to 'Master/texmf-dist')
| -rw-r--r-- | Master/texmf-dist/doc/context/third/markdown/examples/context.tex | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/markdown/markdown.css | 325 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/markdown/markdown.html | 2670 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/markdown/markdown.md | 3502 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/generic/markdown/markdown.pdf | bin | 349893 -> 398905 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/markdown/examples/latex.tex | 14 | ||||
| -rw-r--r-- | Master/texmf-dist/scripts/markdown/markdown-cli.lua | 196 | ||||
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/docstrip.cfg | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 7066 | ||||
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.ins | 6 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/context/third/markdown/t-markdown.tex | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/generic/markdown/markdown.tex | 110 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/markdown/markdown.sty | 24 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/luatex/markdown/markdown.lua | 20 |
14 files changed, 13019 insertions, 932 deletions
diff --git a/Master/texmf-dist/doc/context/third/markdown/examples/context.tex b/Master/texmf-dist/doc/context/third/markdown/examples/context.tex index 5c1caf25de1..99c4eb9e5f2 100644 --- a/Master/texmf-dist/doc/context/third/markdown/examples/context.tex +++ b/Master/texmf-dist/doc/context/third/markdown/examples/context.tex @@ -13,9 +13,17 @@ \definetyping [latex] \setuptyping [latex] [option=TEX] \starttext - \markdownInput{example.md} - \startmarkdown +% Typeset the document `example.md` by letting the Markdown package handle +% the conversion internally. +\markdownInput{./example.md} + +% Typeset the document `example.tex` that we prepared separately using the +% Lua command-line interface and that contains a plain TeX representation +% of the document `example.md`. +\doiffileelse{./example.tex}{\input example}{} + +\startmarkdown Here are some non-ASCII characters: *ěščřžýáíé* and ConTeXt special characters: *|*. - \stopmarkdown +\stopmarkdown \stoptext diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.css b/Master/texmf-dist/doc/generic/markdown/markdown.css new file mode 100644 index 00000000000..2e2f4fb6c44 --- /dev/null +++ b/Master/texmf-dist/doc/generic/markdown/markdown.css @@ -0,0 +1,325 @@ + +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; + } +} + diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.html b/Master/texmf-dist/doc/generic/markdown/markdown.html new file mode 100644 index 00000000000..523805f0347 --- /dev/null +++ b/Master/texmf-dist/doc/generic/markdown/markdown.html @@ -0,0 +1,2670 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> + <meta http-equiv="Content-Style-Type" content="text/css" /> + <meta name="generator" content="pandoc" /> + <meta name="author" content="Vít Novotný" /> + <title>Markdown Package User Manual</title> + <style type="text/css">code{white-space: pre;}</style> + <style type="text/css"> +div.sourceCode { overflow-x: auto; } +table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { + margin: 0; padding: 0; vertical-align: baseline; border: none; } +table.sourceCode { width: 100%; line-height: 100%; } +td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } +td.sourceCode { padding-left: 5px; } +code > span.kw { color: #007020; font-weight: bold; } /* Keyword */ +code > span.dt { color: #902000; } /* DataType */ +code > span.dv { color: #40a070; } /* DecVal */ +code > span.bn { color: #40a070; } /* BaseN */ +code > span.fl { color: #40a070; } /* Float */ +code > span.ch { color: #4070a0; } /* Char */ +code > span.st { color: #4070a0; } /* String */ +code > span.co { color: #60a0b0; font-style: italic; } /* Comment */ +code > span.ot { color: #007020; } /* Other */ +code > span.al { color: #ff0000; font-weight: bold; } /* Alert */ +code > span.fu { color: #06287e; } /* Function */ +code > span.er { color: #ff0000; font-weight: bold; } /* Error */ +code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */ +code > span.cn { color: #880000; } /* Constant */ +code > span.sc { color: #4070a0; } /* SpecialChar */ +code > span.vs { color: #4070a0; } /* VerbatimString */ +code > span.ss { color: #bb6688; } /* SpecialString */ +code > span.im { } /* Import */ +code > span.va { color: #19177c; } /* Variable */ +code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */ +code > span.op { color: #666666; } /* Operator */ +code > span.bu { } /* BuiltIn */ +code > span.ex { } /* Extension */ +code > span.pp { color: #bc7a00; } /* Preprocessor */ +code > span.at { color: #7d9029; } /* Attribute */ +code > span.do { color: #ba2121; font-style: italic; } /* Documentation */ +code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */ +code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */ +code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */ + </style> + <link rel="stylesheet" href="markdown.css" type="text/css" /> +</head> +<body> +<div id="header"> +<h1 class="title">Markdown Package User Manual</h1> +<h2 class="author">Vít Novotný</h2> +</div> +<div id="TOC"> +<ul> +<li><a href="#introduction"><span class="toc-section-number">1</span> Introduction</a><ul> +<li><a href="#requirements"><span class="toc-section-number">1.1</span> Requirements</a></li> +<li><a href="#installation"><span class="toc-section-number">1.2</span> Installation</a><ul> +<li><a href="#local-installation"><span class="toc-section-number">1.2.1</span> Local installation</a></li> +<li><a href="#portable-installation"><span class="toc-section-number">1.2.2</span> Portable installation</a></li> +</ul></li> +<li><a href="#first-document"><span class="toc-section-number">1.3</span> First document</a><ul> +<li><a href="#using-lua"><span class="toc-section-number">1.3.1</span> Using Lua</a><ul> +<li><a href="#using-the-lua-module"><span class="toc-section-number">1.3.1.1</span> Using the Lua module</a></li> +<li><a href="#using-the-lua-cli"><span class="toc-section-number">1.3.1.2</span> Using the Lua CLI</a></li> +</ul></li> +<li><a href="#using-plain-tex"><span class="toc-section-number">1.3.2</span> Using plain TeX</a></li> +<li><a href="#using-latex"><span class="toc-section-number">1.3.3</span> Using LaTeX</a></li> +<li><a href="#using-context"><span class="toc-section-number">1.3.4</span> Using ConTeXt</a></li> +</ul></li> +</ul></li> +<li><a href="#examples"><span class="toc-section-number">2</span> Examples</a><ul> +<li><a href="#lua"><span class="toc-section-number">2.1</span> Lua</a><ul> +<li><a href="#interfaces"><span class="toc-section-number">2.1.1</span> Interfaces</a><ul> +<li><a href="#the-lua-module"><span class="toc-section-number">2.1.1.1</span> The Lua module</a></li> +<li><a href="#the-lua-cli"><span class="toc-section-number">2.1.1.2</span> The Lua CLI</a></li> +</ul></li> +<li><a href="#options"><span class="toc-section-number">2.1.2</span> Options</a><ul> +<li><a href="#file-and-directory-names"><span class="toc-section-number">2.1.2.1</span> File and Directory Names</a><ul> +<li><a href="#option-cachedir"><span class="toc-section-number">2.1.2.1.1</span> Option <code>cacheDir</code></a></li> +</ul></li> +<li><a href="#parser-options"><span class="toc-section-number">2.1.2.2</span> Parser Options</a><ul> +<li><a href="#option-blankbeforeblockquote"><span class="toc-section-number">2.1.2.2.1</span> Option <code>blankBeforeBlockquote</code></a></li> +<li><a href="#option-blankbeforecodefence"><span class="toc-section-number">2.1.2.2.2</span> Option <code>blankBeforeCodeFence</code></a></li> +<li><a href="#option-blankbeforeheading"><span class="toc-section-number">2.1.2.2.3</span> Option <code>blankBeforeHeading</code></a></li> +<li><a href="#option-breakableblockquotes"><span class="toc-section-number">2.1.2.2.4</span> Option <code>breakableBlockquotes</code></a></li> +<li><a href="#option-citationnbsps"><span class="toc-section-number">2.1.2.2.5</span> Option <code>citationNbsps</code></a></li> +<li><a href="#option-citations"><span class="toc-section-number">2.1.2.2.6</span> Option <code>citations</code></a></li> +<li><a href="#option-codespans"><span class="toc-section-number">2.1.2.2.7</span> Option <code>codeSpans</code></a></li> +<li><a href="#option-contentblocks"><span class="toc-section-number">2.1.2.2.8</span> Option <code>contentBlocks</code></a></li> +<li><a href="#option-contentblockslanguagemap"><span class="toc-section-number">2.1.2.2.9</span> Option <code>contentBlocksLanguageMap</code></a></li> +<li><a href="#option-definitionlists"><span class="toc-section-number">2.1.2.2.10</span> Option <code>definitionLists</code></a></li> +<li><a href="#option-fencedcode"><span class="toc-section-number">2.1.2.2.11</span> Option <code>fencedCode</code></a></li> +<li><a href="#option-footnotes"><span class="toc-section-number">2.1.2.2.12</span> Option <code>footnotes</code></a></li> +<li><a href="#option-hashenumerators"><span class="toc-section-number">2.1.2.2.13</span> Option <code>hashEnumerators</code></a></li> +<li><a href="#option-html"><span class="toc-section-number">2.1.2.2.14</span> Option <code>html</code></a></li> +<li><a href="#option-hybrid"><span class="toc-section-number">2.1.2.2.15</span> Option <code>hybrid</code></a></li> +<li><a href="#option-inlinefootnotes"><span class="toc-section-number">2.1.2.2.16</span> Option <code>inlineFootnotes</code></a></li> +<li><a href="#option-preservetabs"><span class="toc-section-number">2.1.2.2.17</span> Option <code>preserveTabs</code></a></li> +<li><a href="#option-smartellipses"><span class="toc-section-number">2.1.2.2.18</span> Option <code>smartEllipses</code></a></li> +<li><a href="#option-startnumber"><span class="toc-section-number">2.1.2.2.19</span> Option <code>startNumber</code></a></li> +<li><a href="#option-tightlists"><span class="toc-section-number">2.1.2.2.20</span> Option <code>tightLists</code></a></li> +<li><a href="#option-underscores"><span class="toc-section-number">2.1.2.2.21</span> Option <code>underscores</code></a></li> +</ul></li> +</ul></li> +</ul></li> +<li><a href="#plain-tex"><span class="toc-section-number">2.2</span> Plain TeX</a><ul> +<li><a href="#interfaces-1"><span class="toc-section-number">2.2.1</span> Interfaces</a></li> +<li><a href="#options-1"><span class="toc-section-number">2.2.2</span> Options</a></li> +<li><a href="#token-renderers"><span class="toc-section-number">2.2.3</span> Token renderers</a></li> +</ul></li> +<li><a href="#latex"><span class="toc-section-number">2.3</span> LaTeX</a><ul> +<li><a href="#interfaces-2"><span class="toc-section-number">2.3.1</span> Interfaces</a></li> +<li><a href="#options-2"><span class="toc-section-number">2.3.2</span> Options</a></li> +<li><a href="#token-renderers-1"><span class="toc-section-number">2.3.3</span> Token renderers</a></li> +</ul></li> +<li><a href="#context"><span class="toc-section-number">2.4</span> ConTeXt</a><ul> +<li><a href="#interfaces-3"><span class="toc-section-number">2.4.1</span> Interfaces</a></li> +<li><a href="#options-3"><span class="toc-section-number">2.4.2</span> Options</a></li> +<li><a href="#token-renderers-2"><span class="toc-section-number">2.4.3</span> Token renderers</a></li> +</ul></li> +</ul></li> +</ul> +</div> +<p><link href="https://afeld.github.io/emoji-css/emoji.css" rel="stylesheet" /></p> +<h1 id="introduction"><span class="header-section-number">1</span> Introduction</h1> +<p>The <a href="https://ctan.org/pkg/markdown" title="CTAN: Package markdown">Markdown package</a> converts <a href="https://daringfireball.net/projects/markdown/basics/" title="Daring Fireball: Markdown Basics">markdown</a> 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></p> +<p>This document is a user manual for the <a href="https://ctan.org/pkg/markdown" title="CTAN: Package markdown">Markdown package</a>. It provides beginner tutorials and code examples. For an in-depth description of the package requirements, interfaces, and implementation, please refer to the <a href="http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf" title="A Markdown Interpreter for TeX">technical documentation</a>.</p> +<h2 id="requirements"><span class="header-section-number">1.1</span> Requirements</h2> +<p>The package requires a working TeX distribution. <a href="https://www.tug.org/texlive/" title="TeX Live - TeX Users Group">TeX Live</a> ≥ 2013 is known to work and so are recent installation of <a href="https://miktex.org/" title="Home - MiKTeXorg">MikTeX</a>. If you are using a minimal installation of a TeX distribution, please consult the <a href="http://mirrors.ctan.org/macros/generic/markdown/markdown.pdf" title="A Markdown Interpreter for TeX">technical documentation</a> for a detailed list of required packages.</p> +<h2 id="installation"><span class="header-section-number">1.2</span> Installation</h2> +<p>The package comes pre-installed with <a href="https://www.tug.org/texlive/" title="TeX Live - TeX Users Group">TeX Live</a> ≥ 2016 and with recent installations of <a href="https://miktex.org/" title="Home - MiKTeXorg">MikTeX</a>. Unless you explicitly wish to use the latest version of the package, you are encouraged to skip this step.</p> +<p>To install the package, first download the package from the repository using Git:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="fu">git</span> clone https://github.com/witiko/markdown</code></pre></div> +<p>Next, enter the directory named <code>markdown</code> and interpret the file named <code>markdown.ins</code> file using a Unicode-aware TeX engine, such as XeTeX or LuaTeX:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="bu">cd</span> markdown +<span class="ex">luatex</span> markdown.ins</code></pre></div> +<p>This should produce the following files:</p> +<ul> +<li><code>markdown.lua</code> – the Lua module,</li> +<li><code>markdown-cli.lua</code> – the Lua command-line interface,</li> +<li><code>markdown.tex</code> – the plain TeX macro package,</li> +<li><code>markdown.sty</code> – the LaTeX package, and</li> +<li><code>t-markdown.tex</code> – the ConTeXt module.</li> +</ul> +<h3 id="local-installation"><span class="header-section-number">1.2.1</span> Local installation</h3> +<p>To perform a local installation, place the above files into your TeX directory structure. This is generally where the individual files should be placed:</p> +<ul> +<li><code><TEXMF>/tex/luatex/markdown/markdown.lua</code></li> +<li><code><TEXMF>/scripts/markdown/markdown-cli.lua</code></li> +<li><code><TEXMF>/tex/generic/markdown/markdown.tex</code></li> +<li><code><TEXMF>/tex/latex/markdown/markdown.sty</code></li> +<li><code><TEXMF>/tex/context/third/markdown/t-markdown.tex</code></li> +</ul> +<p>where <code><TEXMF></code> corresponds to a root of your TeX distribution, such as <code>/usr/share/texmf</code> and <code>~/texmf</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf</code> on Windows systems. When in doubt, consult the manual of your TeX distribution.</p> +<h3 id="portable-installation"><span class="header-section-number">1.2.2</span> Portable installation</h3> +<p>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.</p> +<h2 id="first-document"><span class="header-section-number">1.3</span> First document</h2> +<p>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.</p> +<h3 id="using-lua"><span class="header-section-number">1.3.1</span> Using Lua</h3> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> hello +<span class="fu">\bye</span></code></pre></div> +<h4 id="using-the-lua-module"><span class="header-section-number">1.3.1.1</span> Using the Lua module</h4> +<p>Using a text editor, create a text document named <code>hello.lua</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode lua"><code class="sourceCode lua"><span class="ot">#</span>!<span class="ot">/</span>usr<span class="ot">/</span>bin<span class="ot">/</span>env texlua +<span class="kw">local</span> kpse <span class="ot">=</span> <span class="fu">require</span><span class="ot">(</span><span class="st">"kpse"</span><span class="ot">)</span> +kpse<span class="ot">.</span>set_program_name<span class="ot">(</span><span class="st">"luatex"</span><span class="ot">)</span> +<span class="kw">local</span> markdown <span class="ot">=</span> <span class="fu">require</span><span class="ot">(</span><span class="st">"markdown"</span><span class="ot">)</span> +<span class="kw">local</span> convert <span class="ot">=</span> markdown<span class="ot">.</span>new<span class="ot">()</span> +<span class="fu">print</span><span class="ot">(</span>convert<span class="ot">(</span><span class="st">"Hello *world*!"</span><span class="ot">))</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> hello.lua <span class="op">></span> hello.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> hello.lua <span class="op">></span> hello.tex +<span class="ex">pdftex</span> document.tex</code></pre></div> +<h4 id="using-the-lua-cli"><span class="header-section-number">1.3.1.2</span> Using the Lua CLI</h4> +<p>Using a text editor, create a text document named <code>hello.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Hello *world*!</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- hello.md hello.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- hello.md hello.tex +<span class="ex">pdftex</span> document.tex</code></pre></div> +<h3 id="using-plain-tex"><span class="header-section-number">1.3.2</span> Using plain TeX</h3> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\markdownBegin</span> +Hello *world*! +<span class="fu">\markdownEnd</span> +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">pdftex</span> --shell-escape document.tex</code></pre></div> +<h3 id="using-latex"><span class="header-section-number">1.3.3</span> Using LaTeX</h3> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +Hello *world*! +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">pdflatex</span> --shell-escape document.tex</code></pre></div> +<hr /> +<p>As the next step, try typesetting the example documents distributed along with the Markdown package:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="fu">git</span> clone https://github.com/witiko/markdown +<span class="bu">cd</span> markdown/examples +<span class="ex">lualatex</span> latex.tex</code></pre></div> +<p>A PDF document named <code>latex.pdf</code> should be produced. Open the text documents <code>latex.tex</code> and <code>example.md</code> in a text editor to see how the example documents are structured. Try changing the documents and typesetting them as follows:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> latex.tex</code></pre></div> +<p>to see the effect of your changes.</p> +<h3 id="using-context"><span class="header-section-number">1.3.4</span> Using ConTeXt</h3> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +Hello *world*! +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texexec</span> --passon=--shell-escape document.tex</code></pre></div> +<hr /> +<p>As the next step, try typesetting the example documents distributed along with the Markdown package:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="fu">git</span> clone https://github.com/witiko/markdown +<span class="bu">cd</span> markdown/examples +<span class="ex">context</span> context.tex</code></pre></div> +<p>A PDF document named <code>context.pdf</code> should be produced. Open the text documents <code>context.tex</code> and <code>example.md</code> in a text editor to see how the example documents are structured. Try changing the documents and typesetting them as follows:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> context.tex</code></pre></div> +<p>to see the effect of your changes.</p> +<h1 id="examples"><span class="header-section-number">2</span> Examples</h1> +<p>This section will show how to use the package by example.</p> +<h2 id="lua"><span class="header-section-number">2.1</span> Lua</h2> +<p>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.</p> +<h3 id="interfaces"><span class="header-section-number">2.1.1</span> Interfaces</h3> +<p>The Lua part of the package exposes two interfaces – the <code>markdown</code> Lua module, and the Lua command-line interface (CLI).</p> +<h4 id="the-lua-module"><span class="header-section-number">2.1.1.1</span> The Lua module</h4> +<p>The <code>markdown</code> Lua module exposes the <code>new(options)</code> method, which creates a converter function from markdown to TeX. The properties of the converter function are specified by the Lua table <code>options</code>. The parameter is optional; when unspecified, the behaviour will be the same as if <code>options</code> were an empty table.</p> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> example +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>example.lua</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode lua"><code class="sourceCode lua"><span class="ot">#</span>!<span class="ot">/</span>usr<span class="ot">/</span>bin<span class="ot">/</span>env texlua +<span class="kw">local</span> kpse <span class="ot">=</span> <span class="fu">require</span><span class="ot">(</span><span class="st">"kpse"</span><span class="ot">)</span> +kpse<span class="ot">.</span>set_program_name<span class="ot">(</span><span class="st">"luatex"</span><span class="ot">)</span> +<span class="kw">local</span> markdown <span class="ot">=</span> <span class="fu">require</span><span class="ot">(</span><span class="st">"markdown"</span><span class="ot">)</span> +<span class="kw">local</span> convert_safe <span class="ot">=</span> markdown<span class="ot">.</span>new<span class="ot">()</span> +<span class="kw">local</span> convert_unsafe <span class="ot">=</span> markdown<span class="ot">.</span>new<span class="ot">({</span>hybrid <span class="ot">=</span> <span class="kw">true</span><span class="ot">})</span> +<span class="kw">local</span> input <span class="ot">=</span> <span class="st">[[$\sqrt{-1}$ *equals* $i$.]]</span> +<span class="fu">print</span><span class="ot">(</span>convert_safe<span class="ot">(</span>input<span class="ot">)</span> <span class="ot">..</span> <span class="st">" "</span> <span class="ot">..</span> convert_unsafe<span class="ot">(</span>input<span class="ot">))</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> example.lua <span class="op">></span> example.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “$\sqrt{-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> example.lua <span class="op">></span> example.tex +<span class="ex">pdftex</span> document.tex</code></pre></div> +<hr /> +<p>Rather than use the <code>texlua</code> interpreter, we can also access the <code>markdown</code> Lua module directly from our document. Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert_safe = markdown.new() + local convert_unsafe = markdown.new({hybrid = true}) + local input = [[<span class="ss">$</span><span class="sc">\noexpand\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>.]] + tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.” In this case, we cannot use pdfTeX, because pdfTeX does not define the <code>\directlua</code> TeX command.</p> +<h4 id="the-lua-cli"><span class="header-section-number">2.1.1.2</span> The Lua CLI</h4> +<p>The Lua command-line interface (CLI) accepts the same options as the <code>markdown</code> Lua module, but now the options are specified as command-line parameters.</p> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> safe<span class="fu">\ \input</span> unsafe +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>example.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">$\sqrt{-1}$ *equals* $i$.</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- example.md safe.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> hybrid=true -- example.md unsafe.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “$\sqrt{-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.” Invoking pdfTeX should have the same effect:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- example.md safe.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> hybrid=true -- example.md unsafe.tex +<span class="ex">pdftex</span> document.tex</code></pre></div> +<h3 id="options"><span class="header-section-number">2.1.2</span> Options</h3> +<p>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.</p> +<h4 id="file-and-directory-names"><span class="header-section-number">2.1.2.1</span> File and Directory Names</h4> +<h5 id="option-cachedir"><span class="header-section-number">2.1.2.1.1</span> Option <code>cacheDir</code></h5> +<dl> +<dt><code>cacheDir</code> (default value: <code>"."</code>)</dt> +<dd><p>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.</p> +<p>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 <code>/tmp</code> on UN*X systems), which gets periodically emptied.</p> +</dd> +</dl> +<h6 id="lua-module-example" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert = markdown.new({cacheDir = "cache"}) + local input = "Hello *world*!" + tex.sprint(convert(input)) } +<span class="fu">\bye</span></code></pre></div> +<p>Create an empty directory named <code>cache</code> next to our text document. Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” Several cache files of the Markdown package will also be produced in the <code>cache</code> directory as we requested using the <code>cacheDir</code> option.</p> +<h6 id="lua-cli-example" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> hello +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>hello.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Hello *world*!</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> cacheDir=cache -- hello.md hello.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” A directory named <code>cache</code> containing several cache files of the Markdown package will also be produced as we requested using the <code>cacheDir</code> option.</p> +<h6 id="plain-tex-example" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownOptionCacheDir{cache} +<span class="fu">\markdownBegin</span> +Hello *world*! +<span class="fu">\markdownEnd</span> +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” A directory named <code>cache</code> containing several cache files of the Markdown package will also be produced as we requested using the <code>cacheDir</code> option.</p> +<h6 id="latex-example" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[cacheDir=cache]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +Hello *world*! +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” A directory named <code>cache</code> containing several cache files of the Markdown package will also be produced as we requested using the <code>cacheDir</code> option.</p> +<h6 id="context-example" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionCacheDir{cache} +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +Hello *world*! +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the text “Hello <em>world</em>!” A directory named <code>cache</code> containing several cache files of the Markdown package will also be produced as we requested using the <code>cacheDir</code> option.</p> +<h4 id="parser-options"><span class="header-section-number">2.1.2.2</span> Parser Options</h4> +<h5 id="option-blankbeforeblockquote"><span class="header-section-number">2.1.2.2.1</span> Option <code>blankBeforeBlockquote</code></h5> +<dl> +<dt><code>blankBeforeBlockquote</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Require a blank line between a paragraph and the following blockquote.</p> +</dd> +<dt>false</dt> +<dd><p>Do not require a blank line between a paragraph and the following blockquote.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-1" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<blockquote> +<p>A quote.</p> +</blockquote> +<p>A paragraph > Not a quote.</p> +</blockquote> +<h6 id="lua-cli-example-1" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">A paragraph. +><span class="dt"> A quote?</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> blankBeforeBlockquote=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<blockquote> +<p>A quote?</p> +</blockquote> +<p>A paragraph. > A quote?</p> +</blockquote> +<h6 id="plain-tex-example-1" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown + +<span class="fu">\markdownBegin</span> +A paragraph. +> A quote. +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeBlockquote{true} +<span class="fu">\markdownBegin</span> +A paragraph. +> Not a quote. +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<blockquote> +<p>A quote.</p> +</blockquote> +<p>A paragraph > Not a quote.</p> +</blockquote> +<h6 id="latex-example-1" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +A paragraph. +> A quote. +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{blankBeforeBlockquote} +A paragraph. +> Not a quote. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<blockquote> +<p>A quote.</p> +</blockquote> +<p>A paragraph > Not a quote.</p> +</blockquote> +<h6 id="context-example-1" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +A paragraph. +> A quote. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeBlockquote{true} +<span class="fu">\startmarkdown</span> +A paragraph. +> Not a quote. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<blockquote> +<p>A quote.</p> +</blockquote> +<p>A paragraph > Not a quote.</p> +</blockquote> +<h5 id="option-blankbeforecodefence"><span class="header-section-number">2.1.2.2.2</span> Option <code>blankBeforeCodeFence</code></h5> +<dl> +<dt><code>blankBeforeCodeFence</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Require a blank line between a paragraph and the following fenced code block.</p> +</dd> +<dt>false</dt> +<dd><p>Do not require a blank line between a paragraph and the following fenced code block.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-2" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<pre><code>A code fence.</code></pre> +<p>A paragraph. <code>Not a code fence.</code></p> +</blockquote> +<h6 id="lua-cli-example-2" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">A paragraph. +``` +A code fence? +```</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> fencedCode=true -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> fencedCode=true blankBeforeCodeFence=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<pre><code>A code fence?</code></pre> +<p>A paragraph. <code>A code fence?</code></p> +</blockquote> +<h6 id="plain-tex-example-2" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownOptionFencedCode{true} + +<span class="fu">\markdownBegin</span> +A paragraph. +``` +A code fence. +``` +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeCodeFence{true} +<span class="fu">\markdownBegin</span> +A paragraph. +``` +Not a code fence. +``` +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<pre><code>A code fence.</code></pre> +<p>A paragraph. <code>Not a code fence.</code></p> +</blockquote> +<h6 id="latex-example-2" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[fencedCode]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +A paragraph. +``` +A code fence. +``` +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{blankBeforeCodeFence} +A paragraph. +``` +Not a code fence. +``` +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<pre><code>A code fence.</code></pre> +<p>A paragraph. <code>Not a code fence.</code></p> +</blockquote> +<h6 id="context-example-2" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionFencedCode{true} +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +A paragraph. +``` +A code fence. +``` +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeCodeFence{true} +<span class="fu">\startmarkdown</span> +A paragraph. +``` +Not a code fence. +``` +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<pre><code>A code fence.</code></pre> +<p>A paragraph. <code>Not a code fence.</code></p> +</blockquote> +<h5 id="option-blankbeforeheading"><span class="header-section-number">2.1.2.2.3</span> Option <code>blankBeforeHeading</code></h5> +<dl> +<dt><code>blankBeforeHeading</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Require a blank line between a paragraph and the following header.</p> +</dd> +<dt>false</dt> +<dd><p>Do not require a blank line between a paragraph and the following header.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-3" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\def</span>\markdownRendererHeadingOne#1{{\bf #1}\par} +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<h1 id="a-heading.">A heading.</h1> +<p>A paragraph. Not a heading. ==============</p> +</blockquote> +<h6 id="lua-cli-example-3" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">A paragraph. +A heading? +==========</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> blankBeforeHeading=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<h1 id="a-heading">A heading?</h1> +<p>A paragraph. A heading? ==========</p> +</blockquote> +<h6 id="plain-tex-example-3" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown + +<span class="fu">\markdownBegin</span> +A paragraph. +A heading. +========== +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeHeading{true} +<span class="fu">\markdownBegin</span> +A paragraph. +Not a heading. +============== +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<h1 id="a-heading.-1">A heading.</h1> +<p>A paragraph. Not a heading. ==============</p> +</blockquote> +<h6 id="latex-example-3" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +A paragraph. +A heading. +========== +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{blankBeforeHeading} +A paragraph. +Not a heading. +============== +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<h1 id="a-heading.-2">A heading.</h1> +<p>A paragraph. Not a heading. ==============</p> +</blockquote> +<h6 id="context-example-3" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +A paragraph. +A heading. +========== +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionBlankBeforeHeading{true} +<span class="fu">\startmarkdown</span> +A paragraph. +Not a heading. +============== +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>A paragraph.</p> +<h1 id="a-heading.-3">A heading.</h1> +<p>A paragraph. Not a heading. ==============</p> +</blockquote> +<h5 id="option-breakableblockquotes"><span class="header-section-number">2.1.2.2.4</span> Option <code>breakableBlockquotes</code></h5> +<dl> +<dt><code>breakableBlockquotes</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>A blank line separates block quotes.</p> +</dd> +<dt>false</dt> +<dd><p>Blank lines in the middle of a block quote are ignored.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-4" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\def</span>\markdownRendererHeadingOne#1{{\bf #1}\par} +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<blockquote> +<p>A single block quote.</p> +</blockquote> +<blockquote> +<p>A block quote.</p> +</blockquote> +<blockquote> +<p>Another block quote.</p> +</blockquote> +</blockquote> +<h6 id="lua-cli-example-4" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">><span class="dt"> A single block quote</span> + +<span class="dt">> or two block quotes?</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> breakableBlockquotes=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<blockquote> +<p>A single block quote or two block quotes?</p> +</blockquote> +<blockquote> +<p>A single block quote</p> +</blockquote> +<blockquote> +<p>or two block quotes?</p> +</blockquote> +</blockquote> +<h6 id="plain-tex-example-4" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown + +<span class="fu">\markdownBegin</span> +> A single + +> block quote. +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionBreakableBlockquotes{true} +<span class="fu">\markdownBegin</span> +> A block quote. + +> Another block quote. +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<blockquote> +<p>A single block quote.</p> +</blockquote> +<blockquote> +<p>A block quote.</p> +</blockquote> +<blockquote> +<p>Another block quote.</p> +</blockquote> +</blockquote> +<h6 id="latex-example-4" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +> A single + +> block quote. +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{breakableBlockquotes} +> A block quote. + +> Another block quote. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<blockquote> +<p>A single block quote.</p> +</blockquote> +<blockquote> +<p>A block quote.</p> +</blockquote> +<blockquote> +<p>Another block quote.</p> +</blockquote> +</blockquote> +<h6 id="context-example-4" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +> A single + +> block quote. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionBreakableBlockquotes{true} +<span class="fu">\startmarkdown</span> +> A block quote. + +> Another block quote. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<blockquote> +<p>A single block quote.</p> +</blockquote> +<blockquote> +<p>A block quote.</p> +</blockquote> +<blockquote> +<p>Another block quote.</p> +</blockquote> +</blockquote> +<h5 id="option-citationnbsps"><span class="header-section-number">2.1.2.2.5</span> Option <code>citationNbsps</code></h5> +<dl> +<dt><code>citationNbsps</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Replace regular spaces with non-breakable spaces inside the prenotes and postnotes of citations produced via the pandoc citation syntax extension.</p> +</dd> +<dt>false</dt> +<dd><p>Do not replace regular spaces with non-breakable spaces inside the prenotes and postnotes of citations produced via the pandoc citation syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-5" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.bib</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode bib"><code class="sourceCode bibtex"><span class="va">@book</span>{<span class="ot">knuth:tex</span>, + <span class="dt">author</span> = "<span class="st">Knuth, Donald Ervin</span>", + <span class="dt">title</span> = "<span class="st">The </span><span class="ch">\TeX</span><span class="st"> book, volume A of Computers and typesetting</span>", + <span class="dt">publisher</span> = "<span class="st">Addison-Wesley</span>", + <span class="dt">year</span> = "<span class="st">1984</span>" }</code></pre></div> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[citations]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +The TeXbook [@knuth:tex, p. 123 and 130] is good. +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{citationNbsps = false} +The TeXbook [@knuth:tex, p. 123 and 130] is good. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="bu">\bibliographystyle</span>{<span class="ex">plain</span>} +<span class="bu">\bibliography</span>{<span class="ex">document.bib</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX and BibTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex +<span class="ex">bibtex</span> document.aux +<span class="ex">lualatex</span> document.tex +<span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text, where the middot (<code>·</code>) denotes a non-breakable space:</p> +<blockquote> +<p>The TeXbook [1, p.·123·and·130] is good.</p> +<p>The TeXbook [1, p. 123 and 130] is good.</p> +<h3 id="references">References</h3> +<p>[1] Donald·Ervin Knuth. <em>The TeXbook, volume A of Computers and typesetting.</em> Addison-Wesley, 1984.</p> +</blockquote> +<h5 id="option-citations"><span class="header-section-number">2.1.2.2.6</span> Option <code>citations</code></h5> +<dl> +<dt><code>citations</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the pandoc citation syntax extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">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.</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the pandoc citation syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-6" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.bib</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode bib"><code class="sourceCode bibtex"><span class="va">@book</span>{<span class="ot">knuth:tex</span>, + <span class="dt">author</span> = "<span class="st">Knuth, Donald Ervin</span>", + <span class="dt">title</span> = "<span class="st">The </span><span class="ch">\TeX</span><span class="st"> book, volume A of Computers and typesetting</span>", + <span class="dt">publisher</span> = "<span class="st">Addison-Wesley</span>", + <span class="dt">year</span> = "<span class="st">1984</span>" }</code></pre></div> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[backend=biber]{<span class="ex">biblatex</span>} +<span class="fu">\addbibresource</span>{document.bib} +<span class="bu">\usepackage</span>[citations]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +The TeXbook [@knuth:tex, p. 123 and 130] was written by @knuth:tex. +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="fu">\printbibliography</span> +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX and Biber from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex +<span class="ex">biber</span> document.bcf +<span class="ex">lualatex</span> document.tex +<span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>The TeXbook [1, p.·123 and 130] was written by Knuth [1].</p> +<h3 id="references-1">References</h3> +<p>[1] Donald Ervin Knuth. <em>The TeXbook, volume A of Computers and typesetting.</em> Addison-Wesley, 1984.</p> +</blockquote> +<h5 id="option-codespans"><span class="header-section-number">2.1.2.2.7</span> Option <code>codeSpans</code></h5> +<dl> +<dt><code>codeSpans</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the code span syntax:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Use the <span class="bn">`printf()`</span> function. +`<span class="bn">`There is a literal backtick (`</span>) here.``</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the code span syntax. This allows you to easily use the quotation mark ligatures in texts that do not contain code spans:</p> +<pre><code>``This is a quote.''</code></pre> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-5" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\par</span> +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert = markdown.new({codeSpans = false}) + local input = + "``This is a quote.'' " .. + "``This is another quote.''" + tex.sprint(convert(input)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><code>This is a code span.''</code>This is no longer a code span.''</p> +<p>“This is a quote.” “This is another quote.”</p> +</blockquote> +<h6 id="lua-cli-example-5" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\par</span> +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">`<span class="bn">`Is this a code span?'' `</span>`Or a quote?''</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> codeSpans=false -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>“Is this a code span?” “Or a quote?”</p> +<p><code>Is this a code span?''</code>Or a quote?''</p> +</blockquote> +<h6 id="plain-tex-example-5" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown + +<span class="fu">\markdownBegin</span> +``This is a code span.'' +``This is no longer a code span.'' +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionCodeSpans{false} +<span class="fu">\markdownBegin</span> +``This is a quote.'' +``This is another quote.'' +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><code>This is a code span.''</code>This is no longer a code span.''</p> +<p>“This is a quote.” “This is another quote.”</p> +</blockquote> +<h6 id="latex-example-7" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +``This is a code span.'' +``This is no longer a code span.'' +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{codeSpans=false} +``This is a quote.'' +``This is another quote.'' +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><code>This is a code span.''</code>This is no longer a code span.''</p> +<p>“This is a quote.” “This is another quote.”</p> +</blockquote> +<h6 id="context-example-5" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +``This is a code span.'' +``This is no longer a code span.'' +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionCodeSpans{false} +<span class="fu">\startmarkdown</span> +``This is a quote.'' +``This is another quote.'' +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><code>This is a code span.''</code>This is no longer a code span.''</p> +<p>“This is a quote.” “This is another quote.”</p> +</blockquote> +<h5 id="option-contentblocks"><span class="header-section-number">2.1.2.2.8</span> Option <code>contentBlocks</code></h5> +<dl> +<dt><code>contentBlocks</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the iA Writer content blocks syntax extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">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</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the iA Writer content blocks syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-8" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>table.csv</code> with the following content:</p> +<pre class="csv"><code>Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847</code></pre> +<p>Create also a text document named <code>markdown-languages.json</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="op">{</span> + <span class="st">"tex"</span><span class="op">:</span> <span class="st">"LaTeX"</span> +<span class="op">}</span></code></pre></div> +<p>Create also a text document named <code>code.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\LaTeX</span>.</code></pre></div> +<p>Create also a text document named <code>part.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">This is a *transcluded markdown document*.</code></pre></div> +<p>Create also a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">minted</span>} +<span class="bu">\usepackage</span>[contentBlocks]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> --shell-escape document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<table> +<thead> +<tr class="header"> +<th>Name</th> +<th>Surname</th> +<th>Born</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>Albert</td> +<td>Einstein</td> +<td>1879</td> +</tr> +<tr class="even"> +<td>Marie</td> +<td>Curie</td> +<td>1867</td> +</tr> +<tr class="odd"> +<td>Thomas</td> +<td>Edison</td> +<td>1847</td> +</tr> +</tbody> +</table> +<p>Table 1: An example table</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\LaTeX</span>.</code></pre></div> +<p>This is a <em>transcluded markdown document</em>.</p> +</blockquote> +<h6 id="context-example-6" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>table.csv</code> with the following content:</p> +<pre class="csv"><code>Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847</code></pre> +<p>Create also a text document named <code>markdown-languages.json</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="op">{</span> + <span class="st">"tex"</span><span class="op">:</span> <span class="st">"ConTeXt"</span> +<span class="op">}</span></code></pre></div> +<p>Create also a text document named <code>code.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\ConTeXt</span>.</code></pre></div> +<p>Create also a text document named <code>part.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">This is a *transcluded markdown document*.</code></pre></div> +<p>Create also a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionContentBlocks{true} +<span class="fu">\definetyping</span> [ConTeXt] +<span class="fu">\setuptyping</span> [ConTeXt] [option=TEX] +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<table> +<thead> +<tr class="header"> +<th>Name</th> +<th>Surname</th> +<th>Born</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>Albert</td> +<td>Einstein</td> +<td>1879</td> +</tr> +<tr class="even"> +<td>Marie</td> +<td>Curie</td> +<td>1867</td> +</tr> +<tr class="odd"> +<td>Thomas</td> +<td>Edison</td> +<td>1847</td> +</tr> +</tbody> +</table> +<p>Table 1: An example table</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\ConTeXt</span>.</code></pre></div> +<p>This is a <em>transcluded markdown document</em>.</p> +</blockquote> +<h5 id="option-contentblockslanguagemap"><span class="header-section-number">2.1.2.2.9</span> Option <code>contentBlocksLanguageMap</code></h5> +<dl> +<dt><code>contentBlocksLanguageMap</code> (default value: <code>"markdown-languages.json"</code>)</dt> +<dd><p>The filename of the JSON file that maps filename extensions to programming language names in the iA Writer content blocks.</p> +</dd> +</dl> +<h6 id="latex-example-9" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>table.csv</code> with the following content:</p> +<pre class="csv"><code>Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847</code></pre> +<p>Create also a text document named <code>language-map.json</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="op">{</span> + <span class="st">"tex"</span><span class="op">:</span> <span class="st">"LaTeX"</span> +<span class="op">}</span></code></pre></div> +<p>Create also a text document named <code>code.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\LaTeX</span>.</code></pre></div> +<p>Create also a text document named <code>part.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">This is a *transcluded markdown document*.</code></pre></div> +<p>Create also a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">minted</span>} +<span class="bu">\usepackage</span>[contentBlocks]{<span class="ex">markdown</span>} +<span class="fu">\markdownSetup</span>{ + contentBlocksLanguageMap = {language-map.json}, +} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> --shell-escape document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<table> +<thead> +<tr class="header"> +<th>Name</th> +<th>Surname</th> +<th>Born</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>Albert</td> +<td>Einstein</td> +<td>1879</td> +</tr> +<tr class="even"> +<td>Marie</td> +<td>Curie</td> +<td>1867</td> +</tr> +<tr class="odd"> +<td>Thomas</td> +<td>Edison</td> +<td>1847</td> +</tr> +</tbody> +</table> +<p>Table 1: An example table</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\LaTeX</span>.</code></pre></div> +<p>This is a <em>transcluded markdown document</em>.</p> +</blockquote> +<h6 id="context-example-7" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>table.csv</code> with the following content:</p> +<pre class="csv"><code>Name,Surname,Born +Albert,Einstein,1879 +Marie,Curie,1867 +Thomas,Edison,1847</code></pre> +<p>Create also a text document named <code>language-map.json</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="op">{</span> + <span class="st">"tex"</span><span class="op">:</span> <span class="st">"ConTeXt"</span> +<span class="op">}</span></code></pre></div> +<p>Create also a text document named <code>code.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\ConTeXt</span>.</code></pre></div> +<p>Create also a text document named <code>part.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">This is a *transcluded markdown document*.</code></pre></div> +<p>Create also a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionContentBlocks{true} +<span class="fu">\def</span>\markdownOptionContentBlocksLanguageMap{language-map.json} +<span class="fu">\definetyping</span> [ConTeXt] +<span class="fu">\setuptyping</span> [ConTeXt] [option=TEX] +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +/table.csv (An example table) +/code.tex (An example code listing) +/part.md (A file transclusion example) +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<table> +<thead> +<tr class="header"> +<th>Name</th> +<th>Surname</th> +<th>Born</th> +</tr> +</thead> +<tbody> +<tr class="odd"> +<td>Albert</td> +<td>Einstein</td> +<td>1879</td> +</tr> +<tr class="even"> +<td>Marie</td> +<td>Curie</td> +<td>1867</td> +</tr> +<tr class="odd"> +<td>Thomas</td> +<td>Edison</td> +<td>1847</td> +</tr> +</tbody> +</table> +<p>Table 1: An example table</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex">This is an example code listing in <span class="fu">\ConTeXt</span>.</code></pre></div> +<p>This is a <em>transcluded markdown document</em>.</p> +</blockquote> +<h5 id="option-definitionlists"><span class="header-section-number">2.1.2.2.10</span> Option <code>definitionLists</code></h5> +<dl> +<dt><code>definitionLists</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the pandoc definition list syntax extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + +<span class="bn"> { some code, part of Definition 2 }</span> + +<span class="bn"> Third paragraph of definition 2.</span></code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the pandoc definition list syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-10" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[definitionLists]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<dl> +<dt>Term 1</dt> +<dd><p>Definition 1</p> +</dd> +<dt>Term 2 with <em>inline markup</em></dt> +<dd><p>Definition 2</p> +<pre><code>{ some code, part of Definition 2 }</code></pre> +<p>Third paragraph of definition 2.</p> +</dd> +</dl> +</blockquote> +<h6 id="context-example-8" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionDefinitionLists{true} +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +Term 1 + +: Definition 1 + +Term 2 with *inline markup* + +: Definition 2 + + { some code, part of Definition 2 } + + Third paragraph of definition 2. +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<dl> +<dt>Term 1</dt> +<dd><p>Definition 1</p> +</dd> +<dt>Term 2 with <em>inline markup</em></dt> +<dd><p>Definition 2</p> +<pre><code>{ some code, part of Definition 2 }</code></pre> +<p>Third paragraph of definition 2.</p> +</dd> +</dl> +</blockquote> +<h5 id="option-fencedcode"><span class="header-section-number">2.1.2.2.11</span> Option <code>fencedCode</code></h5> +<dl> +<dt><code>fencedCode</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the commonmark fenced code block extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">~~~ js +if (a > 3) { +<span class="bn"> moveShip(5 * gravity, DOWN);</span> +} +~~~~~~ + + ``` html + <pre> +<span class="bn"> <code></span> +<span class="bn"> // Some comments</span> +<span class="bn"> line 1 of code</span> +<span class="bn"> line 2 of code</span> +<span class="bn"> line 3 of code</span> +<span class="bn"> </code></span> + </pre> + ```</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the commonmark fenced code block extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-11" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">minted</span>} +<span class="bu">\usepackage</span>[fencedCode]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +~~~ 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> + ``` +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> --shell-escape document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="cf">if</span> (a <span class="op">></span> <span class="dv">3</span>) <span class="op">{</span> + <span class="at">moveShip</span>(<span class="dv">5</span> <span class="op">*</span> gravity<span class="op">,</span> DOWN)<span class="op">;</span> +<span class="op">}</span></code></pre></div> +<div class="sourceCode"><pre class="sourceCode html"><code class="sourceCode html"><span class="kw"><pre></span> + <span class="kw"><code></span> + // Some comments + line 1 of code + line 2 of code + line 3 of code + <span class="kw"></code></span> +<span class="kw"></pre></span></code></pre></div> +</blockquote> +<h6 id="context-example-9" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionFencedCode{true} +<span class="fu">\definetyping</span> [js] +<span class="fu">\definetyping</span> [html] +<span class="fu">\setuptyping</span> [html] [option=XML] +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +~~~ 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> + ``` +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<div class="sourceCode"><pre class="sourceCode js"><code class="sourceCode javascript"><span class="cf">if</span> (a <span class="op">></span> <span class="dv">3</span>) <span class="op">{</span> + <span class="at">moveShip</span>(<span class="dv">5</span> <span class="op">*</span> gravity<span class="op">,</span> DOWN)<span class="op">;</span> +<span class="op">}</span></code></pre></div> +<div class="sourceCode"><pre class="sourceCode html"><code class="sourceCode html"><span class="kw"><pre></span> + <span class="kw"><code></span> + // Some comments + line 1 of code + line 2 of code + line 3 of code + <span class="kw"></code></span> +<span class="kw"></pre></span></code></pre></div> +</blockquote> +<h5 id="option-footnotes"><span class="header-section-number">2.1.2.2.12</span> Option <code>footnotes</code></h5> +<dl> +<dt><code>footnotes</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the pandoc footnote syntax extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Here is a footnote reference,<span class="ot">[^1]</span> and another.<span class="ot">[^longnote]</span> + +<span class="ot">[^1]</span>: Here is the footnote. + +<span class="ot">[^longnote]</span>: Here's one with multiple blocks. + +<span class="bn"> Subsequent paragraphs are indented to show that they</span> +belong to the previous footnote. + +<span class="bn"> { some.code }</span> + +<span class="bn"> The whole paragraph can be indented, or just the</span> +<span class="bn"> first line. In this way, multi-paragraph footnotes</span> +<span class="bn"> work like multi-paragraph list items.</span> + +This paragraph won't be part of the note, because it +isn't indented.</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the pandoc footnote syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-12" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[footnotes]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +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. +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>Here is a footnote reference,<a href="#fn1" class="footnoteRef" id="fnref1"><sup>1</sup></a> and another.<a href="#fn2" class="footnoteRef" id="fnref2"><sup>2</sup></a></p> +<p>This paragraph won't be part of the note, because it isn't indented.</p> +</blockquote> +<h6 id="context-example-10" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionFootnotes{true} +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +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. +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>Here is a footnote reference,<a href="#fn3" class="footnoteRef" id="fnref3"><sup>3</sup></a> and another.<a href="#fn4" class="footnoteRef" id="fnref4"><sup>4</sup></a></p> +<p>This paragraph won't be part of the note, because it isn't indented.</p> +</blockquote> +<h5 id="option-hashenumerators"><span class="header-section-number">2.1.2.2.13</span> Option <code>hashEnumerators</code></h5> +<dl> +<dt><code>hashEnumerators</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the use of hash symbols (<code>#</code>) as ordered item list markers:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">#. Bird +#. McHale +#. Parish</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the use of hash symbols (<code>#</code>) as ordered item list markers.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-13" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +#. Bird +#. McHale +#. Parish +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{hashEnumerators} +#. Bird +#. McHale +#. Parish +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<h1 id="bird">. Bird</h1> +<h1 id="mchale">. McHale</h1> +<h1 id="parish">. Parish</h1> +<ol> +<li>Bird</li> +<li>McHale</li> +<li>Parish</li> +</ol> +</blockquote> +<h6 id="context-example-11" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +#. Bird +#. McHale +#. Parish +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionHashEnumerators{true} +<span class="fu">\startmarkdown</span> +#. Bird +#. McHale +#. Parish +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<h1 id="bird-1">. Bird</h1> +<h1 id="mchale-1">. McHale</h1> +<h1 id="parish-1">. Parish</h1> +<ol> +<li>Bird</li> +<li>McHale</li> +<li>Parish</li> +</ol> +</blockquote> +<h5 id="option-html"><span class="header-section-number">2.1.2.2.14</span> Option <code>html</code></h5> +<dl> +<dt><code>html</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>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.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the recognition of HTML markup. Any HTML markup in the input will be rendered as plain text.</p> +</dd> +</dl> +</dd> +</dl> +<p>When the option is enabled, HTML entities are currently incorrectly parsed. See <a href="https://github.com/Witiko/markdown/issues/38" title="Tabs are stripped even with the `preserveTabs=true` Lua option enabled">the corresponding issue</a> in the package repository.</p> +<h6 id="lua-module-example-6" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\par</span> +<span class="fu">\directlua</span>{ + 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)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><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.</p> +<p>There is support. There is support. There is support.</p> +</blockquote> +<h6 id="lua-cli-example-6" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\par</span> +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode html"><code class="sourceCode html"><span class="kw"><div></span> +*Is there block tag support?* +<span class="kw"></div></span> +*Is there <span class="kw"><inline</span><span class="ot"> tag=</span><span class="st">"tag"</span><span class="kw">></inline></span> support?* +_Is there <span class="co"><!-- comment --></span> support?_ +_Is there <span class="kw"><?</span> HTML instruction <span class="kw">?></span> support?_</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> html=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><div>Is there block tag support?</div> Is there <inline tag=”tag”></inline> support? Is there <!-- comment --> support? Is there <? HTML instruction ?> support?</p> +<p>Is there support? Is there support? Is there support?</p> +</blockquote> +<h6 id="plain-tex-example-6" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts + +<span class="fu">\markdownBegin</span> +<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._ +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionHtml{true} +<span class="fu">\markdownBegin</span> +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><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.</p> +<p>There is support. There is support. There is support.</p> +</blockquote> +<h6 id="latex-example-14" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +<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._ +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{html} +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><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.</p> +<p>There is support. There is support. There is support.</p> +</blockquote> +<h6 id="context-example-12" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +<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._ +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionHtml{true} +<span class="fu">\startmarkdown</span> +<div> +*There is block tag support.* +</div> +*There is <inline tag="tag"></inline> support.* +_There is <!-- comment --> support._ +_There is <? HTML instruction ?> support._ +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p><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.</p> +<p>There is support. There is support. There is support.</p> +</blockquote> +<h5 id="option-hybrid"><span class="header-section-number">2.1.2.2.15</span> Option <code>hybrid</code></h5> +<dl> +<dt><code>hybrid</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>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.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>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.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-7" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert_safe = markdown.new() + local convert_unsafe = markdown.new({hybrid = true}) + local input = [[<span class="ss">$</span><span class="sc">\noexpand\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>.]] + tex.sprint(convert_safe(input) .. " " .. convert_unsafe(input)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.</p> +</blockquote> +<h6 id="lua-cli-example-7" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">$\sqrt{-1}$ *equals* $i$.</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> hybrid=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.</p> +</blockquote> +<h6 id="plain-tex-example-7" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\input</span> lmfonts +<span class="fu">\markdownBegin</span> +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="fu">\markdownEnd</span> +<span class="fu">\def</span>\markdownOptionHybrid{true} +<span class="fu">\markdownBegin</span> +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="fu">\markdownEnd</span> +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.</p> +</blockquote> +<h6 id="latex-example-15" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{hybrid} +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.</p> +</blockquote> +<h6 id="context-example-13" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="fu">\stopmarkdown</span> +<span class="fu">\def</span>\markdownOptionHybrid{true} +<span class="fu">\startmarkdown</span> +<span class="ss">$</span><span class="sc">\sqrt</span><span class="ss">{-1}$</span> *equals* <span class="ss">$i$</span>. +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>$\sqrt {-1}$ <em>equals</em> $i$. √-̅1̅ <em>equals</em> <span class="math inline"><em>i</em></span>.</p> +</blockquote> +<h5 id="option-inlinefootnotes"><span class="header-section-number">2.1.2.2.16</span> Option <code>inlineFootnotes</code></h5> +<dl> +<dt><code>inlineFootnotes</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Enable the pandoc inline footnote syntax extension:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode 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.]</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Disable the pandoc inline footnote syntax extension.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-16" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[footnotes, inlineFootnotes]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +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.] +<span class="kw">\end</span>{<span class="ex">markdown</span>} +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>Here is an inline note.<a href="#fn5" class="footnoteRef" id="fnref5"><sup>5</sup></a></p> +</blockquote> +<h6 id="context-example-14" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionFootnotes{true} +<span class="fu">\def</span>\markdownOptionInlineFootnotes{true} +<span class="fu">\starttext</span> +<span class="fu">\startmarkdown</span> +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.] +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>Here is an inline note.<a href="#fn6" class="footnoteRef" id="fnref6"><sup>6</sup></a></p> +</blockquote> +<h5 id="option-preservetabs"><span class="header-section-number">2.1.2.2.17</span> Option <code>preserveTabs</code></h5> +<dl> +<dt><code>preserveTabs</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Preserve all tabs in the input.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Convert any tabs in the input to spaces.</p> +</dd> +</dl> +</dd> +</dl> +<p>This option is currently non-functional. See <a href="https://github.com/Witiko/markdown/issues/38" title="Tabs are stripped even with the `preserveTabs=true` Lua option enabled">the corresponding issue</a> in the package repository.</p> +<h5 id="option-smartellipses"><span class="header-section-number">2.1.2.2.18</span> Option <code>smartEllipses</code></h5> +<dl> +<dt><code>smartEllipses</code> (default value: <code>false</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Convert any ellipses in the input to the <code>\markdownRendererEllipsis</code> TeX macro.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Preserve all ellipses in the input.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="lua-module-example-8" class="unnumbered">Lua module example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownRendererEllipsis{. . .} +<span class="fu">\input</span> lmfonts +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert = markdown.new() + input = "These are just three regular dots ..." + tex.sprint(convert(input)) } +<span class="fu">\par</span> +<span class="fu">\directlua</span>{ + local markdown = require("markdown") + local convert = markdown.new({smartEllipses = true}) + input = "... and this is a victorian ellipsis." + tex.sprint(convert(input)) } +<span class="fu">\bye</span></code></pre></div> +<p>Then, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>These are just three regular dots ...</p> +<p>. . . and this is a victorian ellipsis.</p> +</blockquote> +<h6 id="lua-cli-example-8" class="unnumbered">Lua CLI example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownRendererEllipsis{. . .} +<span class="fu">\input</span> lmfonts +<span class="fu">\input</span> optionfalse +<span class="fu">\par</span> +<span class="fu">\input</span> optiontrue +<span class="fu">\bye</span></code></pre></div> +<p>Using a text editor, create a text document named <code>content.md</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">Are these just three regular dots, a victorian ellipsis, or ... ?</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> -- content.md optionfalse.tex +<span class="ex">texlua</span> <span class="op"><</span>CLI␣PATHNAME<span class="op">></span> smartEllipses=true -- content.md optiontrue.tex +<span class="ex">luatex</span> document.tex</code></pre></div> +<p>where <code><CLI␣PATHNAME></code> corresponds to the location of the Lua CLI script file, such as <code>~/texmf/scripts/markdown/markdown-cli.lua</code> on UN*X systems or <code>C:\Users\<YOUR␣USERNAME>\texmf\scripts\markdown\markdown-cli.lua</code> on Windows systems. Use the command <code>kpsewhich markdown-cli.lua</code> to locate the Lua CLI script file using <a href="https://tug.org/kpathsea/" title="Kpathsea - TeX Users Group">Kpathsea</a>.</p> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>Are these just three regular dots, a victorian ellipsis, or ... ?</p> +<p>Are these just three regular dots, a victorian ellipsis, or . . . ?</p> +</blockquote> +<h6 id="plain-tex-example-8" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownRendererEllipsis{. . .} + +<span class="fu">\markdownBegin</span> +These are just three regular dots ... +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionSmartEllipses{true} +<span class="fu">\markdownBegin</span> +... and this is a victorian ellipsis. +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>These are just three regular dots ...</p> +<p>. . . and this is a victorian ellipsis.</p> +</blockquote> +<h6 id="latex-example-17" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="fu">\markdownSetup</span>{ + renderers = { + ellipsis = {. . .} }} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +These are just three regular dots ... +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{smartEllipses} +... and this is a victorian ellipsis. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>These are just three regular dots ...</p> +<p>. . . and this is a victorian ellipsis.</p> +</blockquote> +<h6 id="context-example-15" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownRendererEllipsis{. . .} +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +These are just three regular dots ... +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionSmartEllipses{true} +<span class="fu">\startmarkdown</span> +... and this is a victorian ellipsis. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>These are just three regular dots ...</p> +<p>. . . and this is a victorian ellipsis.</p> +</blockquote> +<h5 id="option-startnumber"><span class="header-section-number">2.1.2.2.19</span> Option <code>startNumber</code></h5> +<dl> +<dt><code>startNumber</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Make the number in the first item of an ordered lists significant. The item numbers will be passed to the <code>\markdownRendererOlItemWithNumber</code> TeX macro.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Ignore the numbers in the ordered list items. Each item will only produce a <code>\markdownRendererOlItem</code> TeX macro.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-18" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth item +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{startNumber=false} +The following list does not respect the numbers specified in the +markup: + +3. third item +4. fourth item +5. fifth item +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>The following list respects the numbers specified in the markup:</p> +<ol start="3" style="list-style-type: decimal"> +<li>third item</li> +<li>fourth item</li> +<li>fifth item</li> +</ol> +<p>The following list does not respect the numbers specified in the markup:</p> +<ol style="list-style-type: decimal"> +<li>third item</li> +<li>fourth item</li> +<li>fifth item</li> +</ol> +</blockquote> +<h6 id="context-example-16" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth item +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionStartNumber{false} +<span class="fu">\startmarkdown</span> +The following list respects the numbers specified in the markup: + +3. third item +4. fourth item +5. fifth item +<span class="fu">\stopmarkdown</span> +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>The following list respects the numbers specified in the markup:</p> +<ol start="3" style="list-style-type: decimal"> +<li>third item</li> +<li>fourth item</li> +<li>fifth item</li> +</ol> +<p>The following list does not respect the numbers specified in the markup:</p> +<ol style="list-style-type: decimal"> +<li>third item</li> +<li>fourth item</li> +<li>fifth item</li> +</ol> +</blockquote> +<h5 id="option-tightlists"><span class="header-section-number">2.1.2.2.20</span> Option <code>tightLists</code></h5> +<dl> +<dt><code>tightLists</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Lists whose bullets do not consist of multiple paragraphs will be passed to the <code>\markdownRendererOlBeginTight</code>, <code>\markdownRendererOlEndTight</code>, <code>\markdownRendererUlBeginTight</code>, <code>\markdownRendererUlEndTight</code>, <code>\markdownRendererDlBeginTight</code>, and <code>\markdownRendererDlEndTight</code> TeX macros.</p> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Lists whose bullets do not consist of multiple paragraphs will be treated the same way as lists that do consist of multiple paragraphs.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="latex-example-19" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +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 +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{tightLists=false} +The following list is now also loose: + + - first item + - second item + - third item +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>The following list is tight:</p> +<ul> +<li>first item</li> +<li>second item</li> +<li>third item</li> +</ul> +<p>The following list is loose:</p> +<ul> +<li>first item</li> +<li><p>second item that spans</p> +multiple paragraphs</li> +<li><p>third item</p></li> +</ul> +<p>The following list is now also loose:</p> +<ul> +<li><p>first item</p></li> +<li><p>second item</p></li> +<li><p>third item</p></li> +</ul> +</blockquote> +<h5 id="option-underscores"><span class="header-section-number">2.1.2.2.21</span> Option <code>underscores</code></h5> +<dl> +<dt><code>underscores</code> (default value: <code>true</code>)</dt> +<dd><dl> +<dt>true</dt> +<dd><p>Both underscores and asterisks can be used to denote emphasis and strong emphasis:</p> +<div class="sourceCode"><pre class="sourceCode md"><code class="sourceCode markdown">*single asterisks* +_single underscores_ +**double asterisks** +__double underscores__</code></pre></div> +</dd> +</dl> +</dd> +<dd><dl> +<dt>false</dt> +<dd><p>Only asterisks can be used to denote emphasis and strong emphasis. This makes it easy to write math with the option without the need to constantly escape subscripts.</p> +</dd> +</dl> +</dd> +</dl> +<h6 id="plain-tex-example-9" class="unnumbered">Plain TeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\input</span> markdown +<span class="fu">\def</span>\markdownOptionHybrid{true} + +<span class="fu">\markdownBegin</span> +This is _emphasized text_ and this is a math subscript: <span class="ss">$m</span><span class="sc">\_</span><span class="ss">n$</span>. +<span class="fu">\markdownEnd</span> + +<span class="fu">\def</span>\markdownOptionUnderscores{false} +<span class="fu">\markdownBegin</span> +This is *emphasized text* and this is a math subscript: <span class="ss">$m_n$</span>. +<span class="fu">\markdownEnd</span> + +<span class="fu">\bye</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">luatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +</blockquote> +<h6 id="latex-example-20" class="unnumbered">LaTeX example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="bu">\documentclass</span>{<span class="ex">article</span>} +<span class="bu">\usepackage</span>[hybrid]{<span class="ex">markdown</span>} +<span class="kw">\begin</span>{<span class="ex">document</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown</span>} +This is _emphasized text_ and this is a math subscript: <span class="ss">$m</span><span class="sc">\_</span><span class="ss">n$</span>. +<span class="kw">\end</span>{<span class="ex">markdown</span>} + +<span class="kw">\begin</span>{<span class="ex">markdown*</span>}{underscores=false} +This is *emphasized text* and this is a math subscript: <span class="ss">$m_n$</span>. +<span class="kw">\end</span>{<span class="ex">markdown*</span>} + +<span class="kw">\end</span>{<span class="ex">document</span>}</code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">lualatex</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +</blockquote> +<h6 id="context-example-17" class="unnumbered">ConTeXt example</h6> +<p>Using a text editor, create a text document named <code>document.tex</code> with the following content:</p> +<div class="sourceCode"><pre class="sourceCode tex"><code class="sourceCode latex"><span class="fu">\usemodule</span>[t][markdown] +<span class="fu">\def</span>\markdownOptionHybrid{true} +<span class="fu">\starttext</span> + +<span class="fu">\startmarkdown</span> +This is _emphasized text_ and this is a math subscript: <span class="ss">$m</span><span class="sc">\_</span><span class="ss">n$</span>. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\def</span>\markdownOptionUnderscores{false} +<span class="fu">\startmarkdown</span> +This is *emphasized text* and this is a math subscript: <span class="ss">$m_n$</span>. +<span class="fu">\stopmarkdown</span> + +<span class="fu">\stoptext</span></code></pre></div> +<p>Next, invoke LuaTeX from the terminal:</p> +<div class="sourceCode"><pre class="sourceCode sh"><code class="sourceCode bash"><span class="ex">context</span> document.tex</code></pre></div> +<p>A PDF document named <code>document.pdf</code> should be produced and contain the following text:</p> +<blockquote> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +<p>This is <em>emphasized text</em> and this is a math subscript: <em>mₙ</em>.</p> +</blockquote> +<h2 id="plain-tex"><span class="header-section-number">2.2</span> Plain TeX</h2> +<p>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 <em>token renderer</em> commands that define how the individual markdown elements will be typeset.</p> +<h3 id="interfaces-1"><span class="header-section-number">2.2.1</span> Interfaces</h3> +<!-- TODO --> +<h3 id="options-1"><span class="header-section-number">2.2.2</span> Options</h3> +<!-- TODO --> +<h3 id="token-renderers"><span class="header-section-number">2.2.3</span> Token renderers</h3> +<!-- TODO --> +<h2 id="latex"><span class="header-section-number">2.3</span> LaTeX</h2> +<p>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.</p> +<!-- TODO --> +<h3 id="interfaces-2"><span class="header-section-number">2.3.1</span> Interfaces</h3> +<!-- TODO --> +<h3 id="options-2"><span class="header-section-number">2.3.2</span> Options</h3> +<!-- TODO --> +<h3 id="token-renderers-1"><span class="header-section-number">2.3.3</span> Token renderers</h3> +<!-- TODO --> +<h2 id="context"><span class="header-section-number">2.4</span> ConTeXt</h2> +<p>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.</p> +<h3 id="interfaces-3"><span class="header-section-number">2.4.1</span> Interfaces</h3> +<!-- TODO --> +<h3 id="options-3"><span class="header-section-number">2.4.2</span> Options</h3> +<!-- TODO --> +<h3 id="token-renderers-2"><span class="header-section-number">2.4.3</span> Token renderers</h3> +<!-- TODO --> +<div class="footnotes"> +<hr /> +<ol> +<li id="fn1"><p>Here is the footnote.<a href="#fnref1">↩</a></p></li> +<li id="fn2"><p>Here's one with multiple blocks.</p> +<p>Subsequent paragraphs are indented to show that they belong to the previous footnote.</p> +<pre><code>{ some.code }</code></pre> +<p>The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.<a href="#fnref2">↩</a></p></li> +<li id="fn3"><p>Here is the footnote.<a href="#fnref3">↩</a></p></li> +<li id="fn4"><p>Here's one with multiple blocks.</p> +<p>Subsequent paragraphs are indented to show that they belong to the previous footnote.</p> +<pre><code>{ some.code }</code></pre> +<p>The whole paragraph can be indented, or just the first line. In this way, multi-paragraph footnotes work like multi-paragraph list items.<a href="#fnref4">↩</a></p></li> +<li id="fn5"><p>Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.<a href="#fnref5">↩</a></p></li> +<li id="fn6"><p>Inlines notes are easier to write, since you don't have to pick an identifier and move down to type the note.<a href="#fnref6">↩</a></p></li> +</ol> +</div> +</body> +</html> diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.md b/Master/texmf-dist/doc/generic/markdown/markdown.md new file mode 100644 index 00000000000..7bbfc7fa4f1 --- /dev/null +++ b/Master/texmf-dist/doc/generic/markdown/markdown.md @@ -0,0 +1,3502 @@ + +--- +title: Markdown Package User Manual +author: Vít Novotný +--- + + +<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 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) + + +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. + + +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. + + +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. + + +### 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 +`````` + + +### 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. + + +#### File and Directory Names + + +##### Option `cacheDir` + +`cacheDir` (default value: `"."`) + +: 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. + + +###### 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. + + +#### Parser Options + + +##### Option `blankBeforeBlockquote` + +`blankBeforeBlockquote` (default value: `false`) + +: 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. + + +###### 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. + + +##### Option `blankBeforeCodeFence` + +`blankBeforeCodeFence` (default value: `false`) + +: 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. + + +###### 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. ``` + + +##### Option `blankBeforeHeading` + +`blankBeforeHeading` (default value: `false`) + +: 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. + + +###### 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. ============== + + +##### Option `breakableBlockquotes` + +`breakableBlockquotes` (default value: `false`) + +: true + + : A blank line separates block quotes. + + false + + : Blank lines in the middle of a block quote are ignored. + + +###### 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. + + +##### Option `citationNbsps` + +`citationNbsps` (default value: `true`) + +: 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. + + +###### 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. + + +##### Option `citations` + +`citations` (default value: `false`) + +: 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. + + +###### 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. + + +##### Option `codeSpans` + +`codeSpans` (default value: `true`) + +: 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.'' + ~~~~~~ + + +###### 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.” + + +##### Option `contentBlocks` + +`contentBlocks` (default value: `false`) + +: true + + : Enable the + iA Writer content blocks syntax extension: + + ``` 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. + + +###### 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*. + + +##### Option `contentBlocksLanguageMap` + +`contentBlocksLanguageMap` (default value: `"markdown-languages.json"`) + +: The filename of the JSON file that maps filename extensions to + programming language names in the iA Writer content blocks. + + +###### 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*. + + +##### Option `definitionLists` + +`definitionLists` (default value: `false`) + +: 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. + + +###### 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. + + +##### Option `fencedCode` + +`fencedCode` (default value: `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. + + +###### 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> +> ``` + + +##### Option `footnotes` + +`footnotes` (default value: `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. + + +###### 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. + + +##### Option `hashEnumerators` + +`hashEnumerators` (default value: `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. + + +###### 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 + + +##### Option `html` + +`html` (default value: `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. + + +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. + + +##### Option `hybrid` + +`hybrid` (default value: `true`) + +: 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. + + +###### 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$. + + +##### Option `inlineFootnotes` + +`inlineFootnotes` (default value: `false`) + +: 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. + + +###### 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.] + + +##### Option `preserveTabs` + +`preserveTabs` (default value: `false`) + +: true + + : Preserve all tabs in the input. + +: false + + : Convert any tabs in the input to spaces. + + +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) + + +##### Option `smartEllipses` + +`smartEllipses` (default value: `false`) + +: true + + : Convert any ellipses in the input to the + `\markdownRendererEllipsis` TeX macro. + +: false + + : Preserve all ellipses in the input. + + +###### 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. + + +##### Option `startNumber` + +`startNumber` (default value: `true`) + +: true + + : Make the number in the first item of an ordered lists significant. The + item numbers will be passed to the + `\markdownRendererOlItemWithNumber` TeX macro. + +: false + + : Ignore the numbers in the ordered list items. Each item will only + produce a + `\markdownRendererOlItem` TeX macro. + + +###### 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 + + +##### Option `tightLists` + +`tightLists` (default value: `true`) + +: true + + : Lists whose bullets do not consist of multiple paragraphs will be + passed to the + `\markdownRendererOlBeginTight`, `\markdownRendererOlEndTight`, + `\markdownRendererUlBeginTight`, `\markdownRendererUlEndTight`, + `\markdownRendererDlBeginTight`, and + `\markdownRendererDlEndTight` TeX macros. + +: false + + : Lists whose bullets do not consist of multiple paragraphs will be + treated the same way as lists that do consist of multiple paragraphs. + + +###### 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 + + +##### Option `underscores` + +`underscores` (default value: `true`) + +: 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. + + +###### 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ₙ*. + + +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 --> + + +### Options + +<!-- TODO --> + + +### Token renderers + +<!-- TODO --> + + +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 --> + + +### Options + +<!-- TODO --> + + +### Token renderers + +<!-- TODO --> + + +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 --> + diff --git a/Master/texmf-dist/doc/generic/markdown/markdown.pdf b/Master/texmf-dist/doc/generic/markdown/markdown.pdf Binary files differindex 308b347fc51..567f99aed14 100644 --- a/Master/texmf-dist/doc/generic/markdown/markdown.pdf +++ b/Master/texmf-dist/doc/generic/markdown/markdown.pdf diff --git a/Master/texmf-dist/doc/latex/markdown/examples/latex.tex b/Master/texmf-dist/doc/latex/markdown/examples/latex.tex index c02aedbaaa0..cb7f4edce9e 100644 --- a/Master/texmf-dist/doc/latex/markdown/examples/latex.tex +++ b/Master/texmf-dist/doc/latex/markdown/examples/latex.tex @@ -24,8 +24,16 @@ contentBlocks ]{markdown} \begin{document} - \markdownInput{example.md} - \begin{markdown} +% Typeset the document `example.md` by letting the Markdown package handle +% the conversion internally. +\markdownInput{./example.md} + +% Typeset the document `example.tex` that we prepared separately using the +% Lua command-line interface of the Markdown package and that contains a +% plain TeX representation of the document `example.md`. +\InputIfFileExists{./example.tex}{}{} + +\begin{markdown} Here are some non-ASCII characters: *ěščřžýáíé*. - \end{markdown} +\end{markdown} \end{document} diff --git a/Master/texmf-dist/scripts/markdown/markdown-cli.lua b/Master/texmf-dist/scripts/markdown/markdown-cli.lua new file mode 100644 index 00000000000..d5a65a518f4 --- /dev/null +++ b/Master/texmf-dist/scripts/markdown/markdown-cli.lua @@ -0,0 +1,196 @@ +-- +-- Copyright (C) 2009-2016 John MacFarlane, Hans Hagen +-- +-- Permission is hereby granted, free of charge, to any person obtaining +-- a copy of this software and associated documentation files (the +-- "Software"), to deal in the Software without restriction, including +-- without limitation the rights to use, copy, modify, merge, publish, +-- distribute, sublicense, and/or sell copies of the Software, and to +-- permit persons to whom the Software is furnished to do so, subject to +-- the following conditions: +-- +-- The above copyright notice and this permission notice shall be included +-- in all copies or substantial portions of the Software. +-- +-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +-- EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +-- IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +-- CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +-- TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +-- SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +-- +-- Copyright (C) 2018 Vít Novotný +-- +-- This work may be distributed and/or modified under the +-- conditions of the LaTeX Project Public License, either version 1.3 +-- of this license or (at your option) any later version. +-- The latest version of this license is in +-- +-- http://www.latex-project.org/lppl.txt +-- +-- and version 1.3 or later is part of all distributions of LaTeX +-- version 2005/12/01 or later. +-- +-- This work has the LPPL maintenance status `maintained'. +-- The Current Maintainer of this work is Vít Novotný. +-- +-- Send bug reports, requests for additions and questions +-- either to the GitHub issue tracker at +-- +-- https://github.com/witiko/markdown/issues +-- +-- or to the e-mail address <witiko@mail.muni.cz>. +-- +-- MODIFICATION ADVICE: +-- +-- If you want to customize this file, it is best to make a copy of +-- the source file(s) from which it was produced. Use a different +-- name for your copy(ies) and modify the copy(ies); this will ensure +-- that your modifications do not get overwritten when you install a +-- new release of the standard system. You should also ensure that +-- your modified source file does not generate any modified file with +-- the same name as a standard file. +-- +-- You will also need to produce your own, suitably named, .ins file to +-- control the generation of files from your source file; this file +-- should contain your own preambles for the files it generates, not +-- those in the standard .ins files. +-- +local metadata = { + 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ý"}, + license = "LPPL 1.3" +} + +local defaultOptions = {} +defaultOptions.cacheDir = "." +defaultOptions.blankBeforeBlockquote = false +defaultOptions.blankBeforeCodeFence = false +defaultOptions.blankBeforeHeading = false +defaultOptions.breakableBlockquotes = false +defaultOptions.citationNbsps = true +defaultOptions.citations = false +defaultOptions.codeSpans = true +defaultOptions.contentBlocks = false +defaultOptions.contentBlocksLanguageMap = "markdown-languages.json" +defaultOptions.definitionLists = false +defaultOptions.fencedCode = false +defaultOptions.footnotes = false +defaultOptions.hashEnumerators = false +defaultOptions.html = false +defaultOptions.hybrid = false +defaultOptions.inlineFootnotes = false +defaultOptions.preserveTabs = false +defaultOptions.smartEllipses = false +defaultOptions.startNumber = true +defaultOptions.tightLists = true +defaultOptions.underscores = true + +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 + if arg[i] == "--" then + process_options = false + goto continue + elseif arg[i]:match("=") then + key, value = arg[i]:match("(.-)=(.*)") + 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 + elseif arg[i] == "--help" or arg[i] == "-h" then + print(HELP_STRING) + os.exit() + elseif arg[i] == "--version" or arg[i] == "-v" then + print(VERSION_STRING) + os.exit() + end + end + if input_filename == nil then + input_filename = arg[i] + elseif output_filename == nil then + output_filename = arg[i] + else + error('Unexpected argument: "' .. arg[i] .. '".') + end + ::continue:: +end + +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 + +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") +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 diff --git a/Master/texmf-dist/source/generic/markdown/docstrip.cfg b/Master/texmf-dist/source/generic/markdown/docstrip.cfg index 465fa1838ef..11f5397ec77 100644 --- a/Master/texmf-dist/source/generic/markdown/docstrip.cfg +++ b/Master/texmf-dist/source/generic/markdown/docstrip.cfg @@ -62,7 +62,7 @@ \let\luapostamble\empty \declarepreamble\texpreamble -Copyright (C) 2017 Vít Novotný +Copyright (C) 2018 Vít Novotný This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 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 diff --git a/Master/texmf-dist/source/generic/markdown/markdown.ins b/Master/texmf-dist/source/generic/markdown/markdown.ins index 76ed44df1ef..0965a974b78 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.ins +++ b/Master/texmf-dist/source/generic/markdown/markdown.ins @@ -1,8 +1,12 @@ \input docstrip.tex \generate{\usepreamble\luapreamble\usepostamble\luapostamble \file{markdown.lua}{\from{markdown.dtx}{lua}} + \file{markdown-cli.lua}{\from{markdown.dtx}{lua-cli}} \usepreamble\texpreamble\usepostamble\texpostamble \file{markdown.tex}{\from{markdown.dtx}{tex}} \file{markdown.sty}{\from{markdown.dtx}{latex}} - \file{t-markdown.tex}{\from{markdown.dtx}{context}}} + \file{t-markdown.tex}{\from{markdown.dtx}{context}} + \usepreamble\empty\usepostamble\empty + \file{markdown.md}{\from{markdown.dtx}{manual}} + \file{markdown.css}{\from{markdown.dtx}{manual-css}}} \endbatchfile diff --git a/Master/texmf-dist/tex/context/third/markdown/t-markdown.tex b/Master/texmf-dist/tex/context/third/markdown/t-markdown.tex index a65798af1d0..40f891b19bd 100644 --- a/Master/texmf-dist/tex/context/third/markdown/t-markdown.tex +++ b/Master/texmf-dist/tex/context/third/markdown/t-markdown.tex @@ -6,7 +6,7 @@ %% %% markdown.dtx (with options: `context') %% -%% Copyright (C) 2017 Vít Novotný +%% Copyright (C) 2018 Vít Novotný %% %% This work may be distributed and/or modified under the %% conditions of the LaTeX Project Public License, either version 1.3 diff --git a/Master/texmf-dist/tex/generic/markdown/markdown.tex b/Master/texmf-dist/tex/generic/markdown/markdown.tex index 74f1ca40cfb..8b33ee045de 100644 --- a/Master/texmf-dist/tex/generic/markdown/markdown.tex +++ b/Master/texmf-dist/tex/generic/markdown/markdown.tex @@ -6,7 +6,7 @@ %% %% markdown.dtx (with options: `tex') %% -%% Copyright (C) 2017 Vít Novotný +%% Copyright (C) 2018 Vít Novotný %% %% This work may be distributed and/or modified under the %% conditions of the LaTeX Project Public License, either version 1.3 @@ -45,8 +45,8 @@ %% %% The names of the source files used are shown above. %% -\def\markdownLastModified{2018/01/08}% -\def\markdownVersion{2.5.5}% +\def\markdownLastModified{2018/04/08}% +\def\markdownVersion{2.5.6}% \let\markdownBegin\relax \let\markdownEnd\relax \let\markdownInput\relax @@ -75,6 +75,18 @@ \let\markdownOptionSmartEllipses\undefined \let\markdownOptionStartNumber\undefined \let\markdownOptionTightLists\undefined +\def\markdownOptionStripPercentSigns{false}% +\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} \def\markdownRendererInterblockSeparator{% \markdownRendererInterblockSeparatorPrototype}% \def\markdownRendererLineBreak{% @@ -280,8 +292,8 @@ \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`&}% @@ -326,7 +338,7 @@ \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}% @@ -390,7 +402,6 @@ \ifx\markdownOptionInlineFootnotes\undefined\else inlineFootnotes = \markdownOptionInlineFootnotes, \fi - outputDir = "\markdownOptionOutputDir", \ifx\markdownOptionPreserveTabs\undefined\else preserveTabs = \markdownOptionPreserveTabs, \fi @@ -410,7 +421,7 @@ \def\markdownPrepare{% 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 local md = require("markdown") @@ -427,36 +438,53 @@ local convert = md.new(\markdownLuaOptions) \catcode`\^^I=13% \catcode`|=0% \catcode`\\=12% - |gdef|markdownReadAndConvert#1#2{% - |begingroup% - |immediate|openout|markdownOutputFileStream% - |markdownOptionInputTempFileName% - |markdownInfo{Buffering markdown input into the temporary % - input file "|markdownOptionInputTempFileName" and scanning % - for the closing token sequence "#1"}% - |def|do##1{|catcode`##1=12}|dospecials% - |catcode`| =12% - |markdownMakeOther% - |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{% - |ifx|relax##3|relax% - |immediate|write|markdownOutputFileStream{##1}% - |else% - |def^^M{% - |markdownInfo{The ending token sequence was found}% - |immediate|closeout|markdownOutputFileStream% - |endgroup% - |markdownInput|markdownOptionInputTempFileName% - #2}% - |fi% - ^^M}% - |catcode`|^^I=13% - |def^^I{|markdownReadAndConvertTab}% - |catcode`|^^M=13% - |def^^M##1^^M{% - |def^^M####1^^M{% - |markdownReadAndConvertProcessLine####1#1#1|relax}% - ^^M}% - ^^M}% + |catcode`@=14% + |catcode`|%=12@ + |gdef|markdownReadAndConvert#1#2{@ + |begingroup@ + |immediate|openout|markdownOutputFileStream@ + |markdownOptionInputTempFileName@ + |markdownInfo{Buffering markdown input into the temporary @ + input file "|markdownOptionInputTempFileName" and scanning @ + for the closing token sequence "#1"}@ + |def|do##1{|catcode`##1=12}|dospecials@ + |catcode`| =12@ + |markdownMakeOther@ + |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}@ + |def|markdownReadAndConvertProcessLine##1#1##2#1##3|relax{@ + |ifx|relax##3|relax@ + |immediate|write|markdownOutputFileStream{##1}@ + |else@ + |def^^M{@ + |markdownInfo{The ending token sequence was found}@ + |immediate|closeout|markdownOutputFileStream@ + |endgroup@ + |markdownInput|markdownOptionInputTempFileName@ + #2}@ + |fi@ + ^^M}@ + |catcode`|^^I=13@ + |def^^I{|markdownReadAndConvertTab}@ + |catcode`|^^M=13@ + |def^^M##1^^M{@ + |def^^M####1^^M{@ + |markdownReadAndConvertStripPercentSign####1#1#1|relax}@ + ^^M}@ + ^^M}@ |endgroup \ifnum\markdownMode<2\relax \ifnum\markdownMode=0\relax @@ -502,8 +530,8 @@ 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) if not ran_ok then @@ -542,7 +570,7 @@ local convert = md.new(\markdownLuaOptions) |closein|markdownInputFileStream |markdownLuaExecute{% |markdownPrepare - local input = assert(io.open("#1","r")):read("*a") + local input = assert(io.open("#1", "r"):read("*a")) print(convert(input:gsub("\r\n?", "\n")))}}% |endgroup \endinput diff --git a/Master/texmf-dist/tex/latex/markdown/markdown.sty b/Master/texmf-dist/tex/latex/markdown/markdown.sty index f60dc234e7e..251a2f62d74 100644 --- a/Master/texmf-dist/tex/latex/markdown/markdown.sty +++ b/Master/texmf-dist/tex/latex/markdown/markdown.sty @@ -6,7 +6,7 @@ %% %% markdown.dtx (with options: `latex') %% -%% Copyright (C) 2017 Vít Novotný +%% Copyright (C) 2018 Vít Novotný %% %% This work may be distributed and/or modified under the %% conditions of the LaTeX Project Public License, either version 1.3 @@ -110,6 +110,8 @@ \def\markdownOptionTightLists{#1}}% \define@key{markdownOptions}{underscores}[true]{% \def\markdownOptionUnderscores{#1}}% +\define@key{markdownOptions}{stripPercentSigns}[true]{% + \def\markdownOptionStripPercentSigns{#1}}% \define@key{markdownRenderers}{interblockSeparator}{% \renewcommand\markdownRendererInterblockSeparator{#1}}% \define@key{markdownRenderers}{lineBreak}{% @@ -410,8 +412,6 @@ 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}% @@ -452,7 +452,7 @@ \ifx\relax#2\relax \VerbatimInput{#1}% \else - \ifx\minted@jobname\undefined + \ifx\minted@code\undefined \ifx\lst@version\undefined \markdownRendererInputFencedCode{#1}{}% \else @@ -482,16 +482,16 @@ 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 \newcount\markdownLaTeXCitationsCounter @@ -539,6 +539,14 @@ \markdownLaTeXBibLaTeXTextCitations \expandafter{\expandafter}% \fi}}} +\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} \newcommand\markdownMakeOther{% \count0=128\relax \loop diff --git a/Master/texmf-dist/tex/luatex/markdown/markdown.lua b/Master/texmf-dist/tex/luatex/markdown/markdown.lua index 61f2b734bbc..25d45c32da2 100644 --- a/Master/texmf-dist/tex/luatex/markdown/markdown.lua +++ b/Master/texmf-dist/tex/luatex/markdown/markdown.lua @@ -58,22 +58,22 @@ -- those in the standard .ins files. -- 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" } + if not modules then modules = { } end modules['markdown'] = metadata local lpeg = require("lpeg") local unicode = require("unicode") local md5 = require("md5") -local M = {} +local M = {metadata = metadata} local defaultOptions = {} defaultOptions.cacheDir = "." -defaultOptions.outputDir = "." defaultOptions.blankBeforeBlockquote = false defaultOptions.blankBeforeCodeFence = false defaultOptions.blankBeforeHeading = false @@ -508,7 +508,7 @@ function M.writer.new(options) return s end function self.pack(name) - return [[\input"]] .. name .. [["\relax]] + return [[\input"]] .. name .. [["\relax{}]] end self.interblocksep = "\\markdownRendererInterblockSeparator\n{}" self.eof = [[\relax]] @@ -573,13 +573,13 @@ function M.writer.new(options) "{",self.string(tit or ""),"}"} end 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)() |