diff options
Diffstat (limited to 'Master/texmf-dist/source/generic/markdown/markdown.dtx')
| -rw-r--r-- | Master/texmf-dist/source/generic/markdown/markdown.dtx | 1281 |
1 files changed, 974 insertions, 307 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx index 4b6b148082d..c16740e2a1a 100644 --- a/Master/texmf-dist/source/generic/markdown/markdown.dtx +++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx @@ -3,8 +3,7 @@ %<*driver> \documentclass{ltxdockit} \usepackage[american]{babel} -\usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted,varioref} -\vrefwarning +\usepackage{amsmath,btxdockit,doc,fancyvrb,graphicx,hologo,microtype,minted} % Set up the style. \usepackage{xcolor} @@ -87,6 +86,7 @@ hybrid, inlineFootnotes, jekyllData, + relativeReferences, stripPercentSigns, underscores = false, theme = witiko/dot, @@ -763,12 +763,11 @@ abbr { publisher = {Addison-Wesley}} %</techdoc-bibliography> %<*latex-themes-witiko-markdown-techdoc> -\ProvidesPackage{markdownthemewitiko_markdown_techdoc}[2021/09/10] +\ProvidesPackage{markdownthemewitiko_markdown_techdoc}[2022/02/23] \RequirePackage{etoolbox} \markdownSetup{ - renderers = { + rendererPrototypes = { codeSpan = {\inline{#1}}, - link = {#1\footnote{See \url{#3}.}}, headingFour = {% \paragraph{#1}\leavevmode \def\markdownRendererInterblockSeparator{% @@ -783,10 +782,38 @@ abbr { {\def\addcontentsline##1##2##3{}\listoffigures}% }% }, + headerAttributeContextBegin = { + \markdownSetup{ + rendererPrototypes = { + attributeIdentifier = {% + \begingroup + \def\next####1{% + \def####1########1{% + \endgroup + ####1{########1}% + \label{sec:##1}% + }% + }% + \next\markdownRendererHeadingOne + \next\markdownRendererHeadingTwo + \next\markdownRendererHeadingThree + \next\markdownRendererHeadingFour + \next\markdownRendererHeadingFive + \next\markdownRendererHeadingSix + }, + }, + }% + }, }, } +\def\markdownLaTeXRendererAbsoluteLink#1#2#3#4{% + #1\footnote{See \url{#3}.}} +\RequirePackage{varioref} +\vrefwarning +\def\markdownLaTeXRendererRelativeLink#1{% + \ref{#1}} \markdownSetupSnippet{options}{ - renderers = { + rendererPrototypes = { dlBegin = {\begin{optionlist}}, dlItem = { #1 @@ -812,7 +839,6 @@ abbr { dlEnd = {\end{optionlist}}, } } -\RequirePackage{expl3} \ExplSyntaxOn \keys_define:nn { markdown/jekyllData } @@ -866,8 +892,8 @@ syntax is encouraged. đ % 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 \vref{sec:interfaces} describes the interfaces -% exposed by the package. Section \vref{sec:implementation} describes the +% its prerequisites. Section <#sec:interfaces> describes the interfaces +% exposed by the package. Section <#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] @@ -894,7 +920,7 @@ local metadata = { 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-2021 VĂt NovotnĂ˝"}, + "2016-2022 VĂt NovotnĂ˝"}, license = "LPPL 1.3c" } @@ -997,8 +1023,8 @@ a directory named `markdown` due to [issue #74][issue-74]. % % This section gives an overview of all resources required by the package. % -%### Lua Requirements -% \label{sec:luaprerequisites} +%### Lua Requirements {#luaprerequisites} +% % The Lua part of the package requires that the following Lua modules are % available from within the Lua\TeX{} engine: % @@ -1074,11 +1100,11 @@ local md5 = require("md5") % \par % \begin{markdown} % -%### Plain \TeX{} Requirements -% \label{sec:texprerequisites} +%### Plain \TeX{} Requirements {#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 \vref{sec:luaprerequisites}), and the following Lua module: +% Section <#sec:luaprerequisites>), and the following Lua module: % % \pkg{Lua File System} % @@ -1096,7 +1122,7 @@ local md5 = require("md5") % engine~[@luatex17, Section~3.3]. % % Unless you convert markdown documents to \TeX{} manually using the Lua -% command-line interface (see Section \vref{sec:lua-cli-interface}), the plain +% command-line interface (see Section <#sec:lua-cli-interface>), the plain % \TeX{} part of the package will require that either the Lua\TeX{} % \mref{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 @@ -1114,8 +1140,8 @@ local md5 = require("md5") % \par % \begin{markdown} % -%### \LaTeX{} Requirements -% \label{sec:latexprerequisites} +%### \LaTeX{} Requirements {#latexprerequisites} +% % The \LaTeX{} part of the package requires that the \Hologo{LaTeX2e} format is % loaded, % \end{markdown} @@ -1130,7 +1156,7 @@ local md5 = require("md5") % \fi % \begin{markdown} % a \TeX{} engine that extends \Hologo{eTeX}, all the plain \TeX{} -% prerequisites (see Section \vref{sec:texprerequisites}), and the following +% prerequisites (see Section <#sec:texprerequisites>), and the following % \Hologo{LaTeX2e} packages: % % \pkg{keyval} @@ -1160,10 +1186,10 @@ local md5 = require("md5") % % The following packages are soft prerequisites. They are only used to provide % default token renderer prototypes (see sections -% \vref{sec:texrendererprototypes} and -% \vref{sec:latexdefaultrendererprototypes}) or \LaTeX{} themes (see Section -% \vref{sec:latexthemes}) and will not be loaded if the `plain` package option -% has been enabled (see Section \vref{sec:latexplain}): +% <#sec:texrendererprototypes> and +% <#sec:latexdefaultrendererprototypes>) or \LaTeX{} themes (see Section +% <#sec:latexthemes>) and will not be loaded if the `plain` package option +% has been enabled (see Section <#sec:latexplain>): % % \pkg{url} % @@ -1186,7 +1212,7 @@ local md5 = require("md5") %: 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, in the `witiko/dot` \LaTeX{} -% theme (see Section \vref{sec:latexthemes}), and to provide default token +% theme (see Section <#sec:latexthemes>), and to provide default token % renderer prototypes. % % \pkg{fancyvrb} @@ -1215,7 +1241,7 @@ local md5 = require("md5") % %: A package that catches the contents of a file and puts it in a macro. It % is used in the `witiko/graphicx/http` \LaTeX{} theme, see Section -% \vref{sec:latexthemes}. +% <#sec:latexthemes>. % % \pkg{grffile} % @@ -1224,21 +1250,27 @@ local md5 = require("md5") % Since \TeX{} Live${}\geq{}2020$, the functionality of the package has % been integrated in the \LaTeXe{} kernel. It is used in the `witiko/dot` % and `witiko/graphicx/http` \LaTeX{} themes, see Section -% \vref{sec:latexthemes}. +% <#sec:latexthemes>. % % \pkg{etoolbox} % %: A package that is used to polyfill the general hook management system in % the default renderer prototypes for \acro{yaml} metadata, see Section -% \ref{sec:latexyamlmetadata}. +% <#sec:latexyamlmetadata>, and also in the default renderer prototype +% for attribute identifiers. % % \pkg{expl3} % %: A package that enables the expl3 language from the \LaTeX3 kernel in % \TeX{} Live${}\leq{}2019$. It is used in the default renderer prototypes -% for \acro{yaml} metadata, see Section \ref{sec:latexyamlmetadata}. +% for links (see Section <#sec:latexlinks>), \acro{yaml} metadata (see +% Section <#sec:latexyamlmetadata>), and in the implementation of +% \LaTeX{} themes (see Section <#sec:latexthemesimplementation>). % % \end{markdown} +% \begin{macrocode} +\RequirePackage{expl3} +% \end{macrocode} % \iffalse %</latex> %<*context> @@ -1249,14 +1281,14 @@ local md5 = require("md5") %### \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 \vref{sec:texprerequisites}), and the following \Hologo{ConTeXt} +% Section <#sec:texprerequisites>), and the following \Hologo{ConTeXt} % modules: % % \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 \vref{sec:texrendererprototypes}). +% Section <#sec:texrendererprototypes>). % % Feedback %--------- @@ -1290,9 +1322,9 @@ local md5 = require("md5") % interfacing with an external interpreter from \TeX{}, the \pkg{filecontents} % package by Scott Pakin and others. % -% Interfaces -%=========== -% \label{sec:interfaces} +% Interfaces {#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. % @@ -1302,7 +1334,7 @@ local md5 = require("md5") % user that if they only access the package through the interface, the future % minor versions of the package should remain backwards compatible. % -% Figure \vref{fig:block-diagram} shows the high-level structure of the Markdown +% Figure <#fig:block-diagram> shows the high-level structure of the Markdown % package: The translation from markdown to \TeX{} *token renderers* is exposed % by the Lua layer. The plain \TeX{} layer exposes the conversion capabilities % of Lua as \TeX{} macros. The \LaTeX{} and \Hologo{ConTeXt} layers provide @@ -1517,9 +1549,8 @@ Each part will be shown by example, leaving the implementation details to the % \par % \begin{markdown} % -% Lua Interface -%-------------- -% \label{sec:luainterface} +% Lua Interface {#luainterface} +%--------------- % % \iffalse %</lua> @@ -1550,7 +1581,7 @@ module and a command-line interface (CLI). % % 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 \vref{sec:teximplementation}) and will be of +% implementation (see Section <#sec:teximplementation>) and will be of % interest to the developers of other packages and Lua modules. % % The Lua interface is implemented by the `markdown` Lua module. @@ -1562,12 +1593,12 @@ local M = {metadata = metadata} % \par % \begin{markdown} % -%### Conversion from Markdown to Plain \TeX{} -% \label{sec:luaconversion} +%### Conversion from Markdown to Plain \TeX{} {#luaconversion} +% % 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 `options` that contains options -% recognized by the Lua interface. (see Section \vref{sec:luaoptions}). The +% recognized by the Lua interface. (see Section <#sec:luaoptions>). The % `options` parameter is optional; when unspecified, the behaviour will be % the same as if `options` were an empty table. % @@ -1739,8 +1770,8 @@ pdftex document.tex % \fi % \begin{markdown} % -%### Options -% \label{sec:luaoptions} +%### Options {#luaoptions} +% % The Lua interface recognizes the following options. When unspecified, the % value of a key is taken from the \luamdef{defaultOptions} table. % @@ -3597,7 +3628,7 @@ defaultOptions.contentBlocks = false % : The filename of the JSON file that maps filename extensions to programming language names in the iA\,Writer content blocks. -% See Section \vref{sec:texcontentblockrenderers} for more information. +% See Section <#sec:texcontentblockrenderers> for more information. % \end{markdown} % \iffalse @@ -4733,11 +4764,11 @@ defaultOptions.headerAttributes = 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. + : Enable the recognition of inline HTML tags, block HTML elements, + HTML comments, HTML instructions, and entities in the input. Inline + HTML tags, block HTML elements and HTML comments will be rendered, HTML + instructions will be ignored, and HTML entities will be replaced with + the corresponding Unicode codepoints. : false @@ -5533,6 +5564,85 @@ defaultOptions.preserveTabs = false %</lua,lua-cli> %<*manual-options> +#### Option `relativeReferences` + +`relativeReferences` (default value: `false`) + +% \fi +% \begin{markdown} +% +% \Optitem[false]{relativeReferences}{\opt{true}, \opt{false}} +% +: true + + : Enable [relative references][1] in autolinks: + + ``` md + I conclude in Section <#conclusion>. + + Conclusion {#conclusion} + ========== + In this paper, we have discovered that most + grandmas would rather eat dinner with their + grandchildren than get eaten. Begone, wolf! + ``` + +: false + + : Disable relative references in autolinks. + + [1]: https://datatracker.ietf.org/doc/html/rfc3986#section-4.2 + +% \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[headerAttributes, relativeReferences]{markdown} +\begin{document} +\begin{markdown} + +I conclude in Section <#conclusion>. + +Conclusion {#conclusion} +========== +In this paper, we have discovered that most +grandmas would rather eat dinner with their +grandchildren than get eaten. Begone, wolf! + +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX twice from the terminal: +``` sh +lualatex document.tex +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following text: + +> I conclude in Section 1. +> +> # 1. Conclusion +> +> In this paper, we have discovered that most grandmas would rather eat dinner +> with their grandchildren than get eaten. Begone, wolf! + +%</manual-options> +%<*lua,lua-cli> +% \fi +% \begin{macrocode} +defaultOptions.relativeReferences = false +% \end{macrocode} +% \par +% \iffalse +%</lua,lua-cli> +%<*manual-options> + #### Option `shiftHeadings` `shiftHeadings` (default value: `0`) @@ -5876,7 +5986,6 @@ defaultOptions.slice = "^ $" %</lua,lua-cli> %<*manual-options> - #### Option `smartEllipses` `smartEllipses` (default value: `false`) @@ -6860,13 +6969,13 @@ defaultOptions.underscores = true % \par % \begin{markdown} % -%### Command-Line Interface -% \label{sec:lua-cli-interface} +%### Command-Line Interface {#lua-cli-interface} +% % The high-level operation of the Markdown package involves the communication % between several programming layers: the plain \TeX{} layer hands markdown % documents to the Lua layer. Lua converts the documents to \TeX{}, and hands % the converted documents back to plain \TeX{} layer for typesetting, see -% Figure \vref{fig:sequence-diagram-tex-interface}. +% Figure <#fig:sequence-diagram-tex-interface>. % % This procedure has the advantage of being fully automated. However, it also % has several important disadvantages: The converted \TeX{} documents are @@ -6878,7 +6987,7 @@ defaultOptions.underscores = true % A solution to the above problems is to decouple the conversion from the % typesetting. For this reason, a command-line Lua interface for converting a % markdown document to \TeX{} is also provided, see -% Figure \vref{fig:sequence-diagram-lua-cli}. +% Figure <#fig:sequence-diagram-lua-cli>. % % \end{markdown} % \begin{figure} @@ -6968,7 +7077,7 @@ for i = 1, #arg do % 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 \vref{sec:luaoptions}. +% Section <#sec:luaoptions>. % \end{markdown} % \begin{macrocode} elseif arg[i]:match("=") then @@ -7067,9 +7176,8 @@ end % \par % \begin{markdown} % -% Plain \TeX{} Interface -%----------------------- -% \label{sec:texinterface} +% Plain \TeX{} Interface {#texinterface} +%------------------------ % % \iffalse %</tex> @@ -7126,7 +7234,7 @@ pdftex --shell-escape document.tex % % The plain \TeX{} interface provides macros for the typesetting of markdown % input from within plain \TeX{}, for setting the Lua interface options (see -% Section \vref{sec:luaoptions}) used during the conversion from markdown to +% Section <#sec:luaoptions>) used during the conversion from markdown to % plain \TeX{} and for changing the way markdown the tokens are rendered. % % \end{markdown} @@ -7145,8 +7253,8 @@ pdftex --shell-escape document.tex % \noindent It is expected that the special plain \TeX{} characters have the % expected category codes, when \mref{input}ting the file. % -%### Typesetting Markdown -% \label{sec:textypesetting} +%### Typesetting Markdown {#textypesetting} +% % The interface exposes the \mdef{markdownBegin}, \mdef{markdownEnd}, and % \mdef{markdownInput} macros. % @@ -7229,12 +7337,11 @@ pdftex --shell-escape document.tex % \bye % ``````` % -%### Options -% \label{sec:texoptions} +%### Options {#texoptions} % % The plain \TeX{} options are represented by \TeX{} commands. Some of them map % directly to the options recognized by the Lua interface (see -% Section \vref{sec:luaoptions}), while some of them are specific to the plain +% Section <#sec:luaoptions>), while some of them are specific to the plain % \TeX{} interface. % % \end{markdown} @@ -7499,7 +7606,7 @@ bug](https://github.com/witiko/markdown/issues). % %#### Lua Interface Options % The following macros map directly to the options recognized by the Lua -% interface (see Section \vref{sec:luaoptions}) and are not processed by the +% interface (see Section <#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. % @@ -7530,6 +7637,7 @@ bug](https://github.com/witiko/markdown/issues). \let\markdownOptionJekyllData\undefined \let\markdownOptionPipeTables\undefined \let\markdownOptionPreserveTabs\undefined +\let\markdownOptionRelativeReferences\undefined \let\markdownOptionShiftHeadings\undefined \let\markdownOptionSlice\undefined \let\markdownOptionSmartEllipses\undefined @@ -7589,7 +7697,7 @@ A PDF document named `document.pdf` should be produced and contain the text % % The \mdef{markdownOptionStripPercentSigns} macro controls whether a percent % sign (`%`) at the beginning of a line will be discarded when buffering -% Markdown input (see Section \vref{sec:buffering}) or not. Notably, this +% Markdown input (see Section <#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). It defaults @@ -7613,9 +7721,8 @@ user to specify how every markdown token should be processed and rendered. % \fi % \begin{markdown} -### Token Renderers +### Token Renderers {#texrenderersuser} -% \label{sec:texrenderersuser} % \end{markdown} % \iffalse @@ -7627,10 +7734,10 @@ In this section, I will describe the individual token renderers. % % The following \TeX{} macros may occur inside the output of the % converter functions exposed by the Lua interface (see Section -% \vref{sec:luaconversion}) and represent the parsed markdown tokens. These +% <#sec:luaconversion>) and represent the parsed markdown tokens. These % macros are intended to be redefined by the user who is typesetting a % document. By default, they point to the corresponding prototypes (see Section -% \vref{sec:texrendererprototypes}). +% <#sec:texrendererprototypes>). #### Tickbox Renderers The macros named \mdef{markdownRendererTickedBox}, @@ -7737,27 +7844,6 @@ into account. ##### \LaTeX{} Example {.unnumbered} -\def\markdownRendererDocumentEnd{% - \endgroup - This is the end of a document.\par -} -\def\markdownRendererDocumentBegin{% - This is the beginning of a document.\par - \begingroup - \def\markdownRendererDocumentBegin{% - This is the beginning of a nested document.\par - \begingroup - \def\markdownRendererDocumentBegin{% - This is the beginning of a nested document.\par - \begingroup - }% - \def\markdownRendererDocumentEnd{% - \endgroup - This is the end of a nested document.\par - }% - }% -} - Using a text editor, create a text document named `nested.md` with the following content: ``` md @@ -8785,8 +8871,8 @@ that the \TeX{} engine has shell access. % % \begin{markdown} -#### Content Block Renderers -\label{sec:texcontentblockrenderers} +#### Content Block Rendere {#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 @@ -11863,12 +11949,17 @@ following text: % % \begin{markdown} -#### Inline HTML Comment Renderer +#### HTML Comment Renderers + The \mdef{markdownRendererInlineHtmlComment} macro represents the contents of an inline \acro{HTML} comment. This macro will only be produced, when the \Opt{html} option is enabled. The macro receives a single argument that corresponds to the contents of the \acro{HTML} comment. +The \mdef{markdownRendererBlockHtmlCommentBegin} and +\mdef{markdownRendererBlockHtmlCommentEnd} macros represent the beginning +and the end of a block \acro{HTML} comment. The macros receive no arguments. + % \end{markdown} % % \iffalse @@ -11884,13 +11975,23 @@ following content: \markdownSetup{ renderers = { inlineHtmlComment = {\marginnote{#1}}, + blockHtmlCommentBegin = {\begin{quote}}, + blockHtmlCommentEnd = {\end{quote}}, }, } \begin{document} \begin{markdown} -A useful use of HTML comments are side notes. +A useful use of inline HTML comments are side notes. <!-- Side notes are displayed in the horizontal margins next to the relevant -passages, which makes them easier for the reader to find than footnotes. --> +passages, which makes them *easier for the reader to find* than footnotes. --> + +We can render block HTML comments as blockquotes: + +<!-- +Here is a block HTML comment with a code example that a programmer might understand: + + foo = bar + baz - 42 +--> \end{markdown} \end{document} ``````` @@ -11903,11 +12004,18 @@ A PDF document named `document.pdf` should be produced and contain the following body text: > A useful use of HTML comments are side notes. +> +> We can render block HTML comments as blockquotes: +> +> > Here is a block HTML comment with a code example that a programmer might +> > understand: +> > +> > foo = bar + baz - 42 The horizontal margins should contain the following text: > Side notes are displayed in the horizontal margins next to the relevant -> passages, which makes them easier for the reader to find than footnotes. +> passages, which makes them *easier for the reader to find* than footnotes. %</manual-tokens> %<*tex> @@ -11916,6 +12024,268 @@ The horizontal margins should contain the following text: % \begin{macrocode} \def\markdownRendererInlineHtmlComment{% \markdownRendererInlineHtmlCommentPrototype}% +\def\markdownRendererBlockHtmlCommentBegin{% + \markdownRendererBlockHtmlCommentBeginPrototype}% +\def\markdownRendererBlockHtmlCommentEnd{% + \markdownRendererBlockHtmlCommentEndPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### HTML Tag and Element Renderers + +The \mdef{markdownRendererInlineHtmlTag} macro represents an opening, closing, +or empty inline \acro{HTML} tag. This macro will only be produced, when the +\Opt{html} option is enabled. The macro receives a single argument that +corresponds to the contents of the \acro{HTML} tag. + +The \mdef{markdownRendererInputBlockHtmlElement} macro represents a block +\acro{HTML} element. This macro will only be produced, when the \Opt{html} +option is enabled. The macro receives a single argument that filename of a file +containing the contents of the \acro{HTML} element. + +% \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[html]{markdown} +\usepackage{marginnote} +\usepackage{verbatim} +\markdownSetup{ + renderers = { + inlineHtmlTag = {\textbf{#1}}, + inputBlockHtmlElement = {\verbatiminput{#1}}, + }, +} +\begin{document} +\begin{markdown} +<b>_Hello,_ world!</b><br/> + +<div>_Hello,_ world!</div> +\end{markdown} +\end{document} +``````` +Next, invoke LuaTeX from the terminal: +``` sh +lualatex document.tex +lualatex document.tex +`````` +A PDF document named `document.pdf` should be produced and contain the +following body text: + +> **<b>**_Hello,_ world!**</b><br/>** +> +> <div>_Hello,_ world!</div> + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererInlineHtmlTag{% + \markdownRendererInlineHtmlTagPrototype}% +\def\markdownRendererInputBlockHtmlElement{% + \markdownRendererInputBlockHtmlElementPrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Attribute Renderers +The following macros are only produced, when the \Opt{headerAttributes} option +is enabled. + +\mdef{markdownRendererAttributeIdentifier} represents the \meta{identifier} of +a markdown element (`id="`\meta{identifier}`"` in HTML and `#`\meta{identifier} +in Markdown's \Opt{headerAttributes} syntax extension). The macro receives a +single attribute that corresponds to the \meta{identifier}. + +\mdef{markdownRendererAttributeClassName} represents the \meta{class name} of a +markdown element (`class="`\meta{class name} ...`"` in HTML and +`.`\meta{class name} in Markdown's \Opt{headerAttributes} syntax extension). +The macro receives a single attribute that corresponds to the \meta{class +name}. + +\mdef{markdownRendererAttributeKeyValue} represents a HTML attribute in the form +\meta{key}`=`\meta{value} that is neither an identifier nor a class name. +The macro receives two attributes that correspond to the \meta{key} and the +\meta{value}, respectively. + +% \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[headerAttributes, underscores=false]{markdown} +\markdownSetup{ + renderers = { + attributeIdentifier = {% + \par + \emph{(Identifier: #1)} + \par + }, + attributeClassName = {% + \par + \emph{(Class name: #1)} + \par + }, + attributeKeyValue = {% + \par + \emph{(Key: #1, Value: #2)} + \par + }, + }, +} +\begin{document} +\begin{markdown} + +# First top-level heading {jane=doe} + +## A subheading {#identifier} + +# Second top-level heading {.class_name} + +\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: + +> # First top-level heading +> +> *(Key: Jane, Value: Doe)* +> +> ## A subheading +> +> *(Identifier: identifier)* +> +> # Second top-level heading +> +> *(Class name: class\_name)* + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererAttributeIdentifier{% + \markdownRendererAttributeIdentifierPrototype}% +\def\markdownRendererAttributeClassName{% + \markdownRendererAttributeClassNamePrototype}% +\def\markdownRendererAttributeKeyValue{% + \markdownRendererAttributeKeyValuePrototype}% +% \end{macrocode} +% \par +% +% \iffalse +%</tex> +%<*manual-tokens> +% \fi +% +% \begin{markdown} + +#### Header Attribute Context Renderers +The following macros are only produced, when the \Opt{headerAttributes} option +is enabled. + +The \mdef{markdownRendererHeaderAttributeContextBegin} and +\mdef{markdownRendererHeaderAttributeContextEnd} macros represent the beginning +and the end of a section in which the attributes of a heading apply. The macros +receive no arguments. + +% \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[headerAttributes]{markdown} +\markdownSetup{ + renderers = { + headerAttributeContextBegin = {% + \par + \emph{(The beginning of a header attribute context)} + \par + }, + headerAttributeContextBegin = {% + \par + \emph{(The end of a header attribute context)} + \par + }, + }, +} +\begin{document} +\begin{markdown} + +# First top-level heading + +## A subheading {#identifier} + +# Second top-level heading {.class_name} + +\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: + +> # First top-level heading +> +> *(The beginning of a header attribute context)* +> +> ## A subheading +> +> *(The end of a header attribute context)* +> +> *(The beginning of a header attribute context)* +> +> # Second top-level heading +> +> *(The end of a header attribute context)* + +%</manual-tokens> +%<*tex> +% \fi +% +% \begin{macrocode} +\def\markdownRendererHeaderAttributeContextBegin{% + \markdownRendererHeaderAttributeContextBeginPrototype}% +\def\markdownRendererHeaderAttributeContextEnd{% + \markdownRendererHeaderAttributeContextEndPrototype}% % \end{macrocode} % \par % @@ -11926,9 +12296,8 @@ The horizontal margins should contain the following text: % % \begin{markdown} -### Token Renderer Prototypes +### Token Renderer Prototypes {#texrendererprototypes} -% \label{sec:texrendererprototypes} % % \end{markdown} % \iffalse @@ -12049,19 +12418,24 @@ following text: % \begin{markdown} % % The following \TeX{} macros provide definitions for the token renderers (see -% Section \vref{sec:texrenderersuser}) that have not been redefined by the +% Section <#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 -% \vref{sec:lateximplementation} and \vref{sec:contextimplementation}). +% <#sec:lateximplementation> and <#sec:contextimplementation>). % % \end{markdown} % \begin{macrocode} +\def\markdownRendererAttributeIdentifierPrototype#1{}% +\def\markdownRendererAttributeClassNamePrototype#1{}% +\def\markdownRendererAttributeKeyValuePrototype#1#2{}% \def\markdownRendererDocumentBeginPrototype{}% \def\markdownRendererDocumentEndPrototype{}% \def\markdownRendererInterblockSeparatorPrototype{}% \def\markdownRendererLineBreakPrototype{}% \def\markdownRendererEllipsisPrototype{}% +\def\markdownRendererHeaderAttributeContextBeginPrototype{}% +\def\markdownRendererHeaderAttributeContextEndPrototype{}% \def\markdownRendererNbspPrototype{}% \def\markdownRendererLeftBracePrototype{}% \def\markdownRendererRightBracePrototype{}% @@ -12129,6 +12503,10 @@ following text: \def\markdownRendererTextCitePrototype#1{}% \def\markdownRendererTablePrototype#1#2#3{}% \def\markdownRendererInlineHtmlCommentPrototype#1{}% +\def\markdownRendererBlockHtmlCommentBeginPrototype{\iffalse}% +\def\markdownRendererBlockHtmlCommentEndPrototype{\fi}% +\def\markdownRendererInlineHtmlTagPrototype#1{}% +\def\markdownRendererInputBlockHtmlElementPrototype#1{}% \def\markdownRendererTickedBoxPrototype{}% \def\markdownRendererHalfTickedBoxPrototype{}% \def\markdownRendererUntickedBoxPrototype{}% @@ -12189,7 +12567,7 @@ following text: % \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 \vref{sec:directlua}), the first argument may not contain the +% Section <#sec:directlua>), the first argument may not contain the % string `]]` (regardless of the category code of the bracket symbol (`]`)). % % The \mdef{markdownMode} macro specifies how the plain \TeX{} implementation @@ -12233,9 +12611,8 @@ following text: % \par % \begin{markdown} % -% \LaTeX{} Interface -%------------------- -% \label{sec:latexinterface} +% \LaTeX{} Interface {#latexinterface} +%-------------------- % % \end{markdown} % \iffalse @@ -12293,10 +12670,10 @@ pdflatex --shell-escape document.tex % % The \LaTeX{} interface provides \LaTeX{} environments for the typesetting of % markdown input from within \LaTeX{}, facilities for setting Lua interface -% options (see Section \vref{sec:luaoptions}) used during the conversion from +% options (see Section <#sec:luaoptions>) used during the conversion from % markdown to plain \TeX{}, and facilities for changing the way markdown tokens % are rendered. The rest of the interface is inherited from the plain \TeX{} -% interface (see Section \vref{sec:texinterface}). +% interface (see Section <#sec:texinterface>). % % The \LaTeX{} interface is implemented by the `markdown.sty` file, which % can be loaded from the \LaTeX{} document preamble as follows: @@ -12306,10 +12683,10 @@ pdflatex --shell-escape document.tex % \end{Verbatim} % \begin{markdown} % where \meta{options} are the \LaTeX{} interface options (see Section -% \vref{sec:latexoptions}). Note that \meta{options} inside the \mref{usepackage} +% <#sec:latexoptions>). Note that \meta{options} inside the \mref{usepackage} % macro may not set the `markdownRenderers` (see Section -% \vref{sec:latexrenderers}) and `markdownRendererPrototypes` (see Section -% \vref{sec:latexrendererprototypes}) keys. This limitation is due to the way +% <#sec:latexrenderers>) and `markdownRendererPrototypes` (see Section +% <#sec:latexrendererprototypes>) keys. This limitation is due to the way % \Hologo{LaTeX2e} parses package options. % % \end{markdown} @@ -12323,7 +12700,7 @@ pdflatex --shell-escape document.tex % The \envmref{markdown} and \envmref{markdown*} \LaTeX{} environments are used to % typeset markdown document fragments. The starred version of the % \envmref{markdown} environment accepts \LaTeX{} interface options (see -% Section \vref{sec:latexoptions}) as its only argument. These options will +% Section <#sec:latexoptions>) as its only argument. These options will % only influence this markdown document fragment. % % \end{markdown} @@ -12360,7 +12737,7 @@ pdflatex --shell-escape document.tex % the filename of a markdown document and expands to the result of the % conversion of the input markdown document to plain \TeX{}. Unlike the % \mref{markdownInput} macro provided by the plain \TeX{} interface, this macro -% also accepts \LaTeX{} interface options (see Section \vref{sec:latexoptions}) +% also accepts \LaTeX{} interface options (see Section <#sec:latexoptions>) % as its optional argument. These options will only influnce this markdown % document. % @@ -12376,25 +12753,24 @@ pdflatex --shell-escape document.tex % \end{document} % ``````` % -%### Options -% \label{sec:latexoptions} +%### Options {#latexoptions} % % The \LaTeX{} options are represented by a comma-delimited list of % \meta{key}`=`\meta{value} pairs. For boolean options, the `=`\meta{value} % part is optional, and \meta{key} will be interpreted as \meta{key}`=true` % if the `=`\meta{value} part has been omitted. % -% Except for the `plain` option described in Section \vref{sec:latexplain}, and -% the \LaTeX{} themes described in Section \vref{sec:latexthemes}, and the -% \LaTeX{} setup snippets described in Section \vref{sec:latexsetupsnippets}, +% Except for the `plain` option described in Section <#sec:latexplain>, and +% the \LaTeX{} themes described in Section <#sec:latexthemes>, and the +% \LaTeX{} setup snippets described in Section <#sec:latexsetupsnippets>, % \LaTeX{} options map directly to the options recognized by the plain -% \TeX{} interface (see Section \vref{sec:texoptions}) and to the markdown token +% \TeX{} interface (see Section <#sec:texoptions>) and to the markdown token % renderers and their prototypes recognized by the plain \TeX{} interface (see -% Sections \vref{sec:texrenderersuser} and \vref{sec:texrendererprototypes}). +% Sections <#sec:texrenderersuser> and <#sec:texrendererprototypes>). % % The \LaTeX{} options may be specified when loading the \LaTeX{} package, when % using the \envmref{markdown*} \LaTeX{} environment or the \mref{markdownInput} -% macro (see Section \vref{sec:latexinterface}), or via the \mdef{markdownSetup} +% macro (see Section <#sec:latexinterface>), or via the \mdef{markdownSetup} % macro. The \mref{markdownSetup} macro receives the options to set up as its only % argument: % @@ -12428,8 +12804,8 @@ pdflatex --shell-escape document.tex % \end{macrocode} % \begin{markdown} % -% See Section \vref{sec:latexthemes} for information on interactions between -% setup snippets and \LaTeX{} themes. See Section \vref{sec:latexsetupsnippets} +% See Section <#sec:latexthemes> for information on interactions between +% setup snippets and \LaTeX{} themes. See Section <#sec:latexsetupsnippets> % for information about invoking the stored setup snippets. % % \end{markdown} @@ -12470,16 +12846,16 @@ document: % \par % \begin{markdown} -#### No default token renderer prototypes -% \label{sec:latexplain} +#### No default token renderer prototypes {#latexplain} + Default token renderer prototypes require \LaTeX{} packages that may clash with other packages used in a document. Additionally, if we redefine token renderers and renderer prototypes ourselves, the default definitions will bring no benefit to us. Using the `plain` package option, we can keep the default definitions from the plain \TeX{} implementation -% (see Section \vref{sec:textokenrendererprototypes}) +% (see Section <#sec:textokenrendererprototypes>) and prevent the soft \LaTeX{} prerequisites -% in Section \vref{sec:latexprerequisites} +% in Section <#sec:latexprerequisites> from being loaded: ``` tex @@ -12508,8 +12884,7 @@ from being loaded: % \fi % \begin{markdown} -#### \LaTeX{} themes -% \label{sec:latexthemes} +#### \LaTeX{} themes {#latexthemes} User-contributed \LaTeX{} themes for the Markdown package provide a domain-specific interpretation of some Markdown tokens. Similarly to \LaTeX{} @@ -12575,7 +12950,7 @@ would use the following code in the preamble of your document: % \begin{macrocode} \newif\ifmarkdownLaTeXLoaded \markdownLaTeXLoadedfalse -\AtEndOfPackage{\markdownLaTeXLoadedtrue}% +\AtEndOfPackage{\markdownLaTeXLoadedtrue} \define@key{markdownOptions}{theme}{% \IfSubStr{#1}{/}{}{% \markdownError @@ -12586,23 +12961,11 @@ would use the following code in the preamble of your document: markdowntheme\markdownLaTeXThemePackageName}% \expandafter\markdownLaTeXThemeLoad\expandafter{% \markdownLaTeXThemePackageName}{#1/}}% -\newcommand\markdownLaTeXThemeName{}% -\newcommand\markdownLaTeXThemeLoad[2]{% - \ifmarkdownLaTeXLoaded - \def\markdownLaTeXThemeName{#2}% - \RequirePackage{#1}% - \def\markdownLaTeXThemeName{}% - \else - \AtEndOfPackage{% - \def\markdownLaTeXThemeName{#2}% - \RequirePackage{#1}% - \def\markdownLaTeXThemeName{}}% - \fi}% % \end{macrocode} % \begin{markdown} % % The \LaTeX{} themes have a useful synergy with the setup snippets (see -% Section \vref{sec:latexoptions}): To make it less likely that different +% Section <#sec:latexoptions>): To make it less likely that different % themes will define setup snippets with the same name, we will prepend % \meta{theme name}`/` before the snippet name and use the result as the % snippet name. For example, if the `witiko/dot` theme defines the `product` @@ -12678,7 +13041,7 @@ Example themes provided with the Markdown package include: % \end{document} % ```````` % Typesetting the above document produces the output shown in -% Figure \vref{fig:witiko/dot}. +% Figure <#fig:witiko/dot>. % ``` dot Various formats of mathemathical formulae \label{fig:witiko/dot} % digraph tree { % margin = 0; @@ -12792,7 +13155,7 @@ conference article: % \end{document} % ``````` % Typesetting the above document produces the output shown in -% Figure \vref{fig:witiko/graphicx/http}. +% Figure <#fig:witiko/graphicx/http>. %  The theme requires the \pkg{catchfile} \LaTeX{} package and a Unix-like @@ -12894,11 +13257,11 @@ following text, where the middot (`¡`) denotes a non-breaking space: % \par % \begin{markdown} % -% Please, see Section \vref{sec:latexthemesimplementation} for implementation +% Please, see Section <#sec:latexthemesimplementation> for implementation % details of the example themes. -#### \LaTeX{} setup snippets -% \label{sec:latexsetupsnippets} +#### \LaTeX{} setup snippets {#latexsetupsnippets} + % \end{markdown} % \iffalse @@ -12917,8 +13280,16 @@ various options locally. % \fi % \begin{macrocode} \define@key{markdownOptions}{snippet}{% - \expandafter\markdownSetup\expandafter{% - \the\csname markdownLaTeXSetupSnippet#1\endcsname}}% + \@ifundefined + {markdownLaTeXSetupSnippet#1}{% + \markdownError + {Can't invoke setup snippet #1}% + {The setup snippet is undefined}% + }{% + \expandafter\markdownSetup\expandafter{% + \the\csname markdownLaTeXSetupSnippet#1\endcsname}% + }% + }% % \end{macrocode} % \iffalse %</latex> @@ -12958,7 +13329,7 @@ The following ordered list will be preceded by roman numerals: %#### Plain \TeX{} Interface Options % The following options map directly to the option macros exposed by the plain -% \TeX{} interface (see Section \vref{sec:texoptions}). +% \TeX{} interface (see Section <#sec:texoptions>). % % \markdownEnd % \iffalse @@ -13022,6 +13393,8 @@ The following ordered list will be preceded by roman numerals: \def\markdownOptionPipeTables{#1}}% \define@key{markdownOptions}{preserveTabs}[true]{% \def\markdownOptionPreserveTabs{#1}}% +\define@key{markdownOptions}{relativeReferences}[true]{% + \def\markdownOptionRelativeReferences{#1}}% \define@key{markdownOptions}{smartEllipses}[true]{% \def\markdownOptionSmartEllipses{#1}}% \define@key{markdownOptions}{shiftHeadings}{% @@ -13096,16 +13469,21 @@ The following ordered list will be preceded by roman numerals: % } % ``````` % -%#### Plain \TeX{} Markdown Token Renderers -% \label{sec:latexrenderers} +%#### Plain \TeX{} Markdown Token Renderers {#latexrenderers} % % 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 -% \vref{sec:texrenderersuser}). +% <#sec:texrenderersuser>). % % \end{markdown} % \begin{macrocode} +\define@key{markdownRenderers}{attributeIdentifier}{% + \renewcommand\markdownRendererAttributeIdentifier[1]{#1}}% +\define@key{markdownRenderers}{attributeClassName}{% + \renewcommand\markdownRendererAttributeClassName[1]{#1}}% +\define@key{markdownRenderers}{attributeKeyValue}{% + \renewcommand\markdownRendererAttributeKeyValue[2]{#1}}% \define@key{markdownRenderers}{documentBegin}{% \renewcommand\markdownRendererDocumentBegin{#1}}% \define@key{markdownRenderers}{documentEnd}{% @@ -13116,6 +13494,10 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererLineBreak{#1}}% \define@key{markdownRenderers}{ellipsis}{% \renewcommand\markdownRendererEllipsis{#1}}% +\define@key{markdownRenderers}{headerAttributeContextBegin}{% + \renewcommand\markdownRendererHeaderAttributeContextBegin{#1}}% +\define@key{markdownRenderers}{headerAttributeContextEnd}{% + \renewcommand\markdownRendererHeaderAttributeContextEnd{#1}}% \define@key{markdownRenderers}{nbsp}{% \renewcommand\markdownRendererNbsp{#1}}% \define@key{markdownRenderers}{leftBrace}{% @@ -13250,6 +13632,14 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererTable[3]{#1}}% \define@key{markdownRenderers}{inlineHtmlComment}{% \renewcommand\markdownRendererInlineHtmlComment[1]{#1}}% +\define@key{markdownRenderers}{blockHtmlCommentBegin}{% + \renewcommand\markdownRendererBlockHtmlCommentBegin{#1}}% +\define@key{markdownRenderers}{blockHtmlCommentEnd}{% + \renewcommand\markdownRendererBlockHtmlCommentEnd{#1}}% +\define@key{markdownRenderers}{inlineHtmlTag}{% + \renewcommand\markdownRendererInlineHtmlTag[1]{#1}}% +\define@key{markdownRenderers}{inputBlockHtmlElement}{% + \renewcommand\markdownRendererInputBlockHtmlElement[1]{#1}}% \define@key{markdownRenderers}{tickedBox}{% \renewcommand\markdownRendererTickedBox{#1}}% \define@key{markdownRenderers}{halfTickedBox}{% @@ -13272,15 +13662,21 @@ The following ordered list will be preceded by roman numerals: % } % ``````` % -%#### Plain \TeX{} Markdown Token Renderer Prototypes -% \label{sec:latexrendererprototypes} +%#### Plain \TeX{} Markdown Token Renderer Prototypes {#latexrendererprototypes} +% % 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 \vref{sec:texrendererprototypes}). +% Section <#sec:texrendererprototypes>). % % \end{markdown} % \begin{macrocode} +\define@key{markdownRendererPrototypes}{attributeIdentifier}{% + \renewcommand\markdownRendererAttributeIdentifierPrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{attributeClassName}{% + \renewcommand\markdownRendererAttributeClassNamePrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{attributeKeyValue}{% + \renewcommand\markdownRendererAttributeKeyValuePrototype[2]{#1}}% \define@key{markdownRendererPrototypes}{documentBegin}{% \renewcommand\markdownRendererDocumentBeginPrototype{#1}}% \define@key{markdownRendererPrototypes}{documentEnd}{% @@ -13291,6 +13687,10 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererLineBreakPrototype{#1}}% \define@key{markdownRendererPrototypes}{ellipsis}{% \renewcommand\markdownRendererEllipsisPrototype{#1}}% +\define@key{markdownRendererPrototypes}{headerAttributeContextBegin}{% + \renewcommand\markdownRendererHeaderAttributeContextBeginPrototype{#1}}% +\define@key{markdownRendererPrototypes}{headerAttributeContextEnd}{% + \renewcommand\markdownRendererHeaderAttributeContextEndPrototype{#1}}% \define@key{markdownRendererPrototypes}{nbsp}{% \renewcommand\markdownRendererNbspPrototype{#1}}% \define@key{markdownRendererPrototypes}{leftBrace}{% @@ -13425,6 +13825,14 @@ The following ordered list will be preceded by roman numerals: \renewcommand\markdownRendererTablePrototype[3]{#1}}% \define@key{markdownRendererPrototypes}{inlineHtmlComment}{% \renewcommand\markdownRendererInlineHtmlCommentPrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{blockHtmlCommentBegin}{% + \renewcommand\markdownRendererBlockHtmlCommentBeginPrototype{#1}}% +\define@key{markdownRendererPrototypes}{blockHtmlCommentEnd}{% + \renewcommand\markdownRendererBlockHtmlCommentEndPrototype{#1}}% +\define@key{markdownRendererPrototypes}{inlineHtmlTag}{% + \renewcommand\markdownRendererInlineHtmlTagPrototype[1]{#1}}% +\define@key{markdownRendererPrototypes}{inputBlockHtmlElement}{% + \renewcommand\markdownRendererInputBlockHtmlElementPrototype[1]{#1}}% \define@key{markdownRendererPrototypes}{tickedBox}{% \renewcommand\markdownRendererTickedBoxPrototype{#1}}% \define@key{markdownRendererPrototypes}{halfTickedBox}{% @@ -13451,9 +13859,9 @@ The following ordered list will be preceded by roman numerals: %</latex> %<*context> % \fi -% \Hologo{ConTeXt} Interface -%--------------------------- -% \label{sec:contextinterface} +% +% \Hologo{ConTeXt} Interface {#contextinterface} +%---------------------------- % % \iffalse %</context> @@ -13509,7 +13917,7 @@ texexec --passon=--shell-escape document.tex % 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 -% \vref{sec:texinterface}). +% <#sec:texinterface>). % % \end{markdown} % \begin{macrocode} @@ -13559,14 +13967,14 @@ texexec --passon=--shell-escape document.tex % \stoptext % ``````` % -% Implementation -%=============== -% \label{sec:implementation} +% Implementation {#implementation} +%================ +% % This part of the documentation describes the implementation of the interfaces -% exposed by the package (see Section \vref{sec:interfaces}) and is aimed at the +% exposed by the package (see Section <#sec:interfaces>) and is aimed at the % developers of the package, as well as the curious users. % -% Figure \vref{fig:block-diagram} shows the high-level structure of the Markdown +% Figure <#fig:block-diagram> shows the high-level structure of the Markdown % package: The translation from markdown to \TeX{} *token renderers* is % performed by the Lua layer. The plain \TeX{} layer provides default % definitions for the token renderers. The \LaTeX{} and \Hologo{ConTeXt} layers @@ -13580,9 +13988,9 @@ texexec --passon=--shell-escape document.tex % \fi % \begin{markdown} % -% Lua Implementation -%------------------- -% \label{sec:luaimplementation} +% Lua Implementation {#luaimplementation} +%-------------------- +% % The Lua implementation implements \luamdef{writer} and \luamdef{reader} % objects that provide the conversion from markdown to plain \TeX{}. % @@ -13590,7 +13998,7 @@ texexec --passon=--shell-escape document.tex % other formats, such as DocBook, Groff, or \acro{HTML}. These were stripped % from the module and the remaining markdown reader and plain \TeX{} writer % were hidden behind the converter functions exposed by the Lua interface (see -% Section \vref{sec:luainterface}). +% Section <#sec:luainterface>). % % \end{markdown} % \begin{macrocode} @@ -15993,8 +16401,8 @@ end % \par % \begin{markdown} % -%### Plain \TeX{} Writer -% \label{sec:texwriter} +%### Plain \TeX{} Writer {#texwriter} +% % This section documents the \luamref{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 @@ -16002,7 +16410,7 @@ end % `lunamark/writer/latex.lua` files in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section -% \vref{sec:luainterface}), the \luamref{writer} object is exported, so that the +% <#sec:luainterface>), the \luamref{writer} object is exported, so that the % curious user could easily tinker with the methods of the objects produced by % the \luamref{writer.new} method described below. The user should be aware, % however, that the implementation may change in a future revision. @@ -16016,7 +16424,7 @@ M.writer = {} % % The \luamdef{writer.new} method creates and returns a new \TeX{} writer % object associated with the Lua interface options (see Section -% \vref{sec:luaoptions}) `options`. When `options` are unspecified, it is +% <#sec:luaoptions>) `options`. When `options` are unspecified, it is % assumed that an empty table was passed to the method. % % The objects produced by the \luamref{writer.new} method expose instance methods @@ -16511,10 +16919,10 @@ function M.writer.new(options) local contents = util.intersperse(buffer,"\n") if tight and options.tightLists then return {"\\markdownRendererOlBeginTight\n",contents, - "\n\\markdownRendererOlEndTight "} + "\n\\markdownRendererOlEndTight "} else return {"\\markdownRendererOlBegin\n",contents, - "\n\\markdownRendererOlEnd "} + "\n\\markdownRendererOlEnd "} end end % \end{macrocode} @@ -16534,6 +16942,50 @@ function M.writer.new(options) % \par % \begin{markdown} % +% Define \luamdef{writer->block_html_comment} as a function that will +% transform the contents of a block \acro{HTML} comment, to the output +% format, where `contents` are the contents of the \acro{HTML} comment. +% +% \end{markdown} +% \begin{macrocode} + function self.block_html_comment(contents) + if not self.is_writing then return "" end + return {"\\markdownRendererBlockHtmlCommentBegin\n",contents, + "\n\\markdownRendererBlockHtmlCommentEnd "} + end +% \end{macrocode} +% \par +% \begin{markdown} +% +% Define \luamdef{writer->inline_html_tag} as a function that will +% transform the contents of an opening, closing, or empty inline \acro{HTML} +% tag to the output format, where `contents` are the contents of the +% \acro{HTML} tag. +% +% \end{markdown} +% \begin{macrocode} + function self.inline_html_tag(contents) + return {"\\markdownRendererInlineHtmlTag{",self.string(contents),"}"} + end +% \end{macrocode} +% \par +% \begin{markdown} +% +% Define \luamdef{writer->block_html_element} as a function that will +% transform the contents of a block \acro{HTML} element to the output format, +% where `s` are the contents of the \acro{HTML} element. +% +% \end{markdown} +% \begin{macrocode} + function self.block_html_element(s) + if not self.is_writing then return "" end + local name = util.cache(options.cacheDir, s, nil, nil, ".verbatim") + return {"\\markdownRendererInputBlockHtmlElement{",name,"}"} + 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 `items` is an array of % tables, each of the form `{ term = t, definitions = defs }`, where `t` @@ -16663,8 +17115,23 @@ function M.writer.new(options) % \end{markdown} % \begin{macrocode} function self.document(d) - return {"\\markdownRendererDocumentBegin\n", d, - "\\markdownRendererDocumentEnd"} + local active_attributes = self.active_attributes + local buf = {"\\markdownRendererDocumentBegin\n", d} + + -- pop attributes for sections that have ended + if options.headerAttributes and self.is_writing then + while #active_attributes > 0 do + local attributes = active_attributes[#active_attributes] + if #attributes > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd") + end + table.remove(active_attributes, #active_attributes) + end + end + + table.insert(buf, "\\markdownRendererDocumentEnd") + + return buf end % \end{macrocode} % \par @@ -16765,13 +17232,13 @@ function M.writer.new(options) % \par % \begin{markdown} % -% Define \luamdef{writer->active\_headings} as a stack of identifiers +% Define \luamdef{writer->active\_attributes} as a stack of attributes % of the headings that are currently active. The % \luamref{writer->active\_headings} member variable is mutable. % % \end{markdown} % \begin{macrocode} - self.active_headings = {} + self.active_attributes = {} % \end{macrocode} % \par % \begin{markdown} @@ -16782,50 +17249,99 @@ function M.writer.new(options) % % \end{markdown} % \begin{macrocode} - function self.heading(s,level,attributes) - local active_headings = self.active_headings + function self.heading(s, level, attributes) + attributes = attributes or {} + for i = 1, #attributes do + attributes[attributes[i]] = true + end + + local active_attributes = self.active_attributes local slice_begin_type = self.slice_begin:sub(1, 1) local slice_begin_identifier = self.slice_begin:sub(2) or "" local slice_end_type = self.slice_end:sub(1, 1) local slice_end_identifier = self.slice_end:sub(2) or "" - while #active_headings < level do - -- push empty identifiers for implied sections - table.insert(active_headings, {}) + local buf = {} + + -- push empty attributes for implied sections + while #active_attributes < level-1 do + table.insert(active_attributes, {}) end - while #active_headings >= level do - -- pop identifiers for sections that have ended - local active_identifiers = active_headings[#active_headings] - if active_identifiers[slice_begin_identifier] ~= nil + -- pop attributes for sections that have ended + while #active_attributes >= level do + local active_identifiers = active_attributes[#active_attributes] + -- tear down all active attributes at slice end + if active_identifiers["#" .. slice_end_identifier] ~= nil + and slice_end_type == "$" then + for header_level = #active_attributes, 1, -1 do + if options.headerAttributes and #active_attributes[header_level] > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd") + end + end + self.is_writing = false + end + table.remove(active_attributes, #active_attributes) + if self.is_writing and options.headerAttributes and #active_identifiers > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd") + end + -- apply all active attributes at slice beginning + if active_identifiers["#" .. slice_begin_identifier] ~= nil and slice_begin_type == "$" then + for header_level = 1, #active_attributes do + if options.headerAttributes and #active_attributes[header_level] > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin") + end + end self.is_writing = true end - if active_identifiers[slice_end_identifier] ~= nil - and slice_end_type == "$" then - self.is_writing = false + end + + -- tear down all active attributes at slice end + if attributes["#" .. slice_end_identifier] ~= nil + and slice_end_type == "^" then + for header_level = #active_attributes, 1, -1 do + if options.headerAttributes and #active_attributes[header_level] > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextEnd") + end end - table.remove(active_headings, #active_headings) + self.is_writing = false end - -- push identifiers for the new section - attributes = attributes or {} - local identifiers = {} - for index = 1, #attributes do - attribute = attributes[index] - identifiers[attribute:sub(2)] = true + -- push attributes for the new section + table.insert(active_attributes, attributes) + if self.is_writing and options.headerAttributes and #attributes > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin") end - if identifiers[slice_begin_identifier] ~= nil + + -- apply all active attributes at slice beginning + if attributes["#" .. slice_begin_identifier] ~= nil and slice_begin_type == "^" then + for header_level = 1, #active_attributes do + if options.headerAttributes and #active_attributes[header_level] > 0 then + table.insert(buf, "\\markdownRendererHeaderAttributeContextBegin") + end + end self.is_writing = true end - if identifiers[slice_end_identifier] ~= nil - and slice_end_type == "^" then - self.is_writing = false - end - table.insert(active_headings, identifiers) - if not self.is_writing then return "" end + if self.is_writing then + table.sort(attributes) + local key, value + for i = 1, #attributes do + if attributes[i]:sub(1, 1) == "#" then + table.insert(buf, {"\\markdownRendererAttributeIdentifier{", + attributes[i]:sub(2), "}"}) + elseif attributes[i]:sub(1, 1) == "." then + table.insert(buf, {"\\markdownRendererAttributeClassName{", + attributes[i]:sub(2), "}"}) + else + key, value = attributes[i]:match("(%w+)=(%w+)") + table.insert(buf, {"\\markdownRendererAttributeKeyValue{", + key, "}{", value, "}"}) + end + end + end local cmd level = level + options.shiftHeadings @@ -16844,7 +17360,11 @@ function M.writer.new(options) else cmd = "" end - return {cmd,"{",s,"}"} + if self.is_writing then + table.insert(buf, {cmd, "{", s, "}"}) + end + + return buf end % \end{macrocode} % \par @@ -16900,7 +17420,7 @@ function M.writer.new(options) function self.get_state() return { is_writing=self.is_writing, - active_headings={table.unpack(self.active_headings)}, + active_attributes={table.unpack(self.active_attributes)}, } end % \end{macrocode} @@ -17082,7 +17602,7 @@ parsers.nonemptyline = parsers.line - parsers.blankline % % The \luamdef{parsers.commented_line}`^1` parser recognizes the regular % language of \TeX{} comments, see an equivalent finite automaton in Figure -% \vref{fig:commented_line}. +% <#fig:commented_line>. % % \end{markdown} % \begin{macrocode} @@ -17140,12 +17660,12 @@ parsers.css_identifier = (parsers.hash + parsers.period) * (parsers.css_identifier_char - parsers.digit) * parsers.css_identifier_char^0)) -parsers.attribute_name_char = parsers.any - parsers.space +parsers.attribute_key_char = parsers.any - parsers.space - parsers.squote - parsers.dquote - parsers.more - parsers.slash - parsers.equal -parsers.attribute_value_char = parsers.any - parsers.dquote - - parsers.more +parsers.attribute_value_char = parsers.any - parsers.space + - parsers.dquote - parsers.more -- block followed by 0 or more optionally -- indented blocks with first line indented. @@ -17667,11 +18187,6 @@ end parsers.in_matched_block_tags = parsers.less * Cmt(#parsers.openelt_block, parse_matched_tags) -parsers.displayhtml = parsers.htmlcomment / "" - + parsers.emptyelt_block - + parsers.openelt_exact("hr") - + parsers.in_matched_block_tags - + parsers.htmlinstruction % \end{macrocode} % \par % \begin{markdown} @@ -17786,7 +18301,7 @@ parsers.dlchunk = Cs(parsers.line * (parsers.indentedline - parsers.blankline)^0 % \end{markdown} % \begin{macrocode} parsers.heading_attribute = C(parsers.css_identifier) - + C((parsers.attribute_name_char + + C((parsers.attribute_key_char - parsers.rbrace)^1 * parsers.equal * (parsers.attribute_value_char @@ -17811,22 +18326,22 @@ end % \par % \begin{markdown} % -%### Markdown Reader -% \label{sec:markdownreader} +%### Markdown Reader {#markdownreader} +% % This section documents the \luamref{reader} object, which implements the % routines for parsing the markdown input. The object corresponds to the % markdown reader object that was located in the % `lunamark/reader/markdown.lua` file in the Lunamark Lua module. % % Although not specified in the Lua interface (see Section -% \vref{sec:luainterface}), the \luamref{reader} object is exported, so that the +% <#sec:luainterface>), the \luamref{reader} object is exported, so that the % curious user could easily tinker with the methods of the objects produced by % the \luamref{reader.new} method described below. The user should be aware, % however, that the implementation may change in a future revision. % % The \luamdef{reader.new} method creates and returns a new \TeX{} reader % object associated with the Lua interface options (see Section -% \vref{sec:luaoptions}) `options` and with a writer object `writer`. When +% <#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. % @@ -18349,6 +18864,14 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline "mailto:"..email) end + larsers.AutoLinkRelativeReference + = parsers.less + * C(parsers.urlchar^1) + * parsers.more + / function(url) + return writer.link(writer.escape(url), url) + end + larsers.DirectLink = (parsers.tag / parse_inlines_no_link) -- no links inside links * parsers.spnl * parsers.lparent @@ -18405,12 +18928,12 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline larsers.EscapedChar = parsers.backslash * C(parsers.escapable) / writer.string - larsers.InlineHtml = parsers.emptyelt_any + larsers.InlineHtml = parsers.emptyelt_any / writer.inline_html_tag + (parsers.htmlcomment / parse_inlines_no_html) / writer.inline_html_comment + parsers.htmlinstruction - + parsers.openelt_any - + parsers.closeelt_any + + parsers.openelt_any / writer.inline_html_tag + + parsers.closeelt_any / writer.inline_html_tag larsers.HtmlEntity = parsers.hexentity / entities.hex_entity / writer.string + parsers.decentity / entities.dec_entity / writer.string @@ -18428,7 +18951,12 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline * parsers.contentblock_tail / writer.contentblock - larsers.DisplayHtml = parsers.displayhtml + larsers.DisplayHtml = (parsers.htmlcomment / parse_blocks) + / writer.block_html_comment + + parsers.emptyelt_block / writer.block_html_element + + parsers.openelt_exact("hr") / writer.block_html_element + + parsers.in_matched_block_tags / writer.block_html_element + + parsers.htmlinstruction larsers.Verbatim = Cs( (parsers.blanklines * ((parsers.indentedline - parsers.blankline))^1)^1 @@ -18724,6 +19252,7 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline + V("Code") + V("AutoLinkUrl") + V("AutoLinkEmail") + + V("AutoLinkRelativeReference") + V("InlineHtml") + V("HtmlEntity") + V("EscapedChar") @@ -18744,6 +19273,7 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline + V("Code") + V("AutoLinkUrl") + V("AutoLinkEmail") + + V("AutoLinkRelativeReference") + V("InlineHtml") + V("HtmlEntity") + V("EscapedChar") @@ -18765,6 +19295,8 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline Code = larsers.Code, AutoLinkUrl = larsers.AutoLinkUrl, AutoLinkEmail = larsers.AutoLinkEmail, + AutoLinkRelativeReference + = larsers.AutoLinkRelativeReference, InlineHtml = larsers.InlineHtml, HtmlEntity = larsers.HtmlEntity, EscapedChar = larsers.EscapedChar, @@ -18822,6 +19354,10 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline syntax.Smart = parsers.fail end + if not options.relativeReferences then + syntax.AutoLinkRelativeReference = parsers.fail + end + local blocks_toplevel_t = util.table_copy(syntax) blocks_toplevel_t.Paragraph = larsers.ToplevelParagraph larsers.blocks_toplevel = Ct(blocks_toplevel_t) @@ -18868,7 +19404,7 @@ larsers.PipeTable = Ct(larsers.table_row * parsers.newline % \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 \vref{sec:luaoptions}). The \Opt{cacheDir} option +% Lua interface (see Section <#sec:luaoptions>). The \Opt{cacheDir} option % is disregarded. % \end{markdown} % \begin{macrocode} @@ -18936,7 +19472,7 @@ end %### Conversion from Markdown to Plain \TeX{} % The \luamref{new} method returns the \luamref{reader->convert} function of a reader % object associated with the Lua interface options (see Section -% \vref{sec:luaoptions}) `options` and with a writer object associated with +% <#sec:luaoptions>) `options` and with a writer object associated with % `options`. % % \end{markdown} @@ -18956,10 +19492,10 @@ return M % \par % \begin{markdown} % -%### Command-Line Implementation -% \label{sec:lua-cli-implementation} +%### Command-Line Implementation {#lua-cli-implementation} +% % The command-line implementation provides the actual conversion routine for -% the command-line interface described in Section~\vref{sec:lua-cli-interface}. +% the command-line interface described in Section <#sec:lua-cli-interface>. % % \end{markdown} % \begin{macrocode} @@ -19024,16 +19560,15 @@ end % \par % \begin{markdown} % -% Plain \TeX{} Implementation -%---------------------------- -% \label{sec:teximplementation} +% Plain \TeX{} Implementation {#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 \vref{sec:texinterface}). +% exposed by the plain \TeX{} interface (see Section <#sec:texinterface>). % -%### Logging Facilities -% \label{sec:texinterfacelogging} +%### Logging Facilities {#texinterfacelogging} % % \end{markdown} % \begin{macrocode} @@ -19071,8 +19606,8 @@ end % \par % \begin{markdown} % -%### Token Renderer Prototypes -% \label{sec:textokenrendererprototypes} +%### Token Renderer Prototypes {#textokenrendererprototypes} +% % The following definitions should be considered placeholder. % % \end{markdown} @@ -19149,8 +19684,8 @@ end % %### Lua Snippets % The \mdef{markdownLuaOptions} macro expands to a Lua table that -% contains the plain \TeX{} options (see Section \vref{sec:texoptions}) in a -% format recognized by Lua (see Section \vref{sec:luaoptions}). +% contains the plain \TeX{} options (see Section <#sec:texoptions>) in a +% format recognized by Lua (see Section <#sec:luaoptions>). % % \end{markdown} % \begin{macrocode} @@ -19228,6 +19763,9 @@ end \ifx\markdownOptionPreserveTabs\undefined\else preserveTabs = \markdownOptionPreserveTabs, \fi +\ifx\markdownOptionRelativeReferences\undefined\else + relativeReferences = \markdownOptionRelativeReferences, +\fi \ifx\markdownOptionShiftHeadings\undefined\else shiftHeadings = "\markdownOptionShiftHeadings", \fi @@ -19294,8 +19832,7 @@ end % \par % \begin{markdown} % -%### Buffering Markdown Input -% \label{sec:buffering} +%### Buffering Markdown Input {#buffering} % % The % \mdef{markdownIfOption}`{`\meta{name}`}{`\meta{iftrue}`}{`\meta{iffalse}`}` @@ -19495,14 +20032,14 @@ end % \par % \begin{markdown} % -%### Lua Shell Escape Bridge -% \label{sec:luabridge} +%### Lua Shell Escape Bridge {#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 \mref{markdownMode} values of `0` and `1`. % % The \mref{markdownLuaExecute} macro defined here and in Section -% \vref{sec:directlua} are meant to be indistinguishable to the remaining code. +% <#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 @@ -19666,11 +20203,11 @@ end % \par % \begin{markdown} % -%### Direct Lua Access -% \label{sec:directlua} +%### Direct Lua Access {#directlua} +% % The following \TeX{} code is intended for \TeX{} engines that provide % direct access to Lua (Lua\TeX{}). The macro \mref{markdownLuaExecute} defined -% here and in Section \vref{sec:luabridge} are meant to be indistinguishable to +% here and in Section <#sec:luabridge> are meant to be indistinguishable to % the remaining code. This corresponds to the \mref{markdownMode} value of `2`. % % \end{markdown} @@ -19684,7 +20221,7 @@ end % The direct Lua access version of the \mref{markdownLuaExecute} macro is defined % in terms of the \mref{directlua} primitive. The \luamref{print} function is set as % an alias to the \mref{tex.print} method in order to mimic the behaviour of the -% \mref{markdownLuaExecute} definition from Section \vref{sec:luabridge}, +% \mref{markdownLuaExecute} definition from Section <#sec:luabridge>, % % \end{markdown} % \begin{macrocode} @@ -19806,16 +20343,16 @@ end % \par % \begin{markdown} % -% \LaTeX{} Implementation -%------------------------ -% \label{sec:lateximplementation} +% \LaTeX{} Implementation {#lateximplementation} +%------------------------- +% % The \LaTeX{} implemenation makes use of the fact that, apart from some subtle % 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. % % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section \vref{sec:texinterfacelogging}) to use the \LaTeX{} \mref{PackageInfo}, +% Section <#sec:texinterfacelogging>) to use the \LaTeX{} \mref{PackageInfo}, % \mref{PackageWarning}, and \mref{PackageError} macros. % % \end{markdown} @@ -19833,7 +20370,7 @@ end % %### Logging Facilities % The \LaTeX{} implementation redefines the plain \TeX{} logging macros (see -% Section \vref{sec:texinterfacelogging}) to use the \LaTeX{} \mref{PackageInfo}, +% Section <#sec:texinterfacelogging>) to use the \LaTeX{} \mref{PackageInfo}, % \mref{PackageWarning}, and \mref{PackageError} macros. % % \end{markdown} @@ -19846,7 +20383,7 @@ end % The \mdef{markdownInputPlainTeX} macro is used to store the original plain % \TeX{} implementation of the \mref{markdownInput} macro. The \mref{markdownInput} % is then redefined to accept an optional argument with options recognized by -% the \LaTeX{} interface (see Section \vref{sec:latexoptions}). +% the \LaTeX{} interface (see Section <#sec:latexoptions>). % % \end{markdown} % \begin{macrocode} @@ -19892,36 +20429,55 @@ end % \par % \begin{markdown} % -%### Options -% The supplied package options are processed using the \mref{markdownSetup} macro. +%#### \LaTeX{} Themes {#latexthemesimplementation} +% +% This section implements the theme-loading mechanism and the example themes +% provided with the Markdown package. % % \end{markdown} % \begin{macrocode} -\DeclareOption*{% - \expandafter\markdownSetup\expandafter{\CurrentOption}}% -\ProcessOptions\relax +\ExplSyntaxOn % \end{macrocode} % \begin{markdown} % -% After processing the options, activate the `renderers` and -% `rendererPrototypes` keys. +% To keep track of our current place when packages themes have been nested, +% we will maintain the \mdef{g_\@\@_latex_themes_seq} stack of theme names. % % \end{markdown} % \begin{macrocode} -\define@key{markdownOptions}{renderers}{% - \setkeys{markdownRenderers}{#1}% - \def\KV@prefix{KV@markdownOptions@}}% -\define@key{markdownOptions}{rendererPrototypes}{% - \setkeys{markdownRendererPrototypes}{#1}% - \def\KV@prefix{KV@markdownOptions@}}% +\newcommand\markdownLaTeXThemeName{} +\seq_new:N \g_@@_latex_themes_seq +\seq_put_right:NV + \g_@@_latex_themes_seq + \markdownLaTeXThemeName +\newcommand\markdownLaTeXThemeLoad[2]{ + \def\@tempa{% + \def\markdownLaTeXThemeName{#2} + \seq_put_right:NV + \g_@@_latex_themes_seq + \markdownLaTeXThemeName + \RequirePackage{#1} + \seq_pop_right:NN + \g_@@_latex_themes_seq + \l_tmpa_tl + \seq_get_right:NN + \g_@@_latex_themes_seq + \l_tmpa_tl + \exp_args:NNV + \def + \markdownLaTeXThemeName + \l_tmpa_tl} + \ifmarkdownLaTeXLoaded + \@tempa + \else + \exp_args:No + \AtEndOfPackage + { \@tempa } + \fi} +\ExplSyntaxOff % \end{macrocode} -% \par % \begin{markdown} % -%#### \LaTeX{} Themes -% \label{sec:latexthemesimplementation} -% This section implements example themes provided with the Markdown package. -% % The `witiko/dot` theme enables the \Opt{fencedCode} Lua option: % % \end{markdown} @@ -19935,7 +20491,7 @@ end % \begin{markdown} % % We load the \pkg{ifthen} and \pkg{grffile} packages, see also -% Section~\ref{sec:latexprerequisites}: +% Section <#sec:latexprerequisites>: % % \end{markdown} % \begin{macrocode} @@ -20009,7 +20565,7 @@ end % \begin{markdown} % % We load the \pkg{catchfile} and \pkg{grffile} packages, see also -% Section~\ref{sec:latexprerequisites}: +% Section <#sec:latexprerequisites>: % % \end{markdown} % \begin{macrocode} @@ -20148,10 +20704,36 @@ end % \par % \begin{markdown} % -%### Token Renderer Prototypes -% \label{sec:latexdefaultrendererprototypes} +%### Options +% The supplied package options are processed using the \mref{markdownSetup} macro. +% +% \end{markdown} +% \begin{macrocode} +\DeclareOption*{% + \expandafter\markdownSetup\expandafter{\CurrentOption}}% +\ProcessOptions\relax +% \end{macrocode} +% \begin{markdown} +% +% After processing the options, activate the `renderers` and +% `rendererPrototypes` keys. +% +% \end{markdown} +% \begin{macrocode} +\define@key{markdownOptions}{renderers}{% + \setkeys{markdownRenderers}{#1}% + \def\KV@prefix{KV@markdownOptions@}}% +\define@key{markdownOptions}{rendererPrototypes}{% + \setkeys{markdownRendererPrototypes}{#1}% + \def\KV@prefix{KV@markdownOptions@}}% +% \end{macrocode} +% \par +% \begin{markdown} +% +%### Token Renderer Prototypes {#latexdefaultrendererprototypes} +% % The following configuration should be considered placeholder. If the `plain` -% package option has been enabled (see Section \vref{sec:latexplain}), none of +% package option has been enabled (see Section <#sec:latexplain>), none of % it will take effect. % \end{markdown} % \begin{macrocode} @@ -20289,7 +20871,6 @@ end \ifx\empty#4\empty\else \caption{#4}% \fi - \label{fig:#1}% \end{figure}}, ulBegin = {\begin{itemize}}, ulEnd = {\end{itemize}}, @@ -20303,6 +20884,37 @@ end emphasis = {\emph{#1}}, tickedBox = {$\boxtimes$}, halfTickedBox = {$\boxdot$}, +% \end{macrocode} +% \par +% \begin{markdown} +% +% If identifier attributes appear at the beginning of a section, we make the +% next heading produce the \mref{label} macro. +% +% \end{markdown} +% \begin{macrocode} + headerAttributeContextBegin = { + \markdownSetup{ + rendererPrototypes = { + attributeIdentifier = {% + \begingroup + \def\next####1{% + \def####1########1{% + \endgroup + ####1{########1}% + \label{##1}% + }% + }% + \next\markdownRendererHeadingOne + \next\markdownRendererHeadingTwo + \next\markdownRendererHeadingThree + \next\markdownRendererHeadingFour + \next\markdownRendererHeadingFive + \next\markdownRendererHeadingSix + }, + }, + }% + }, blockQuoteBegin = {\begin{quotation}}, blockQuoteEnd = {\end{quotation}}, inputVerbatim = {\VerbatimInput{#1}}, @@ -20415,6 +21027,40 @@ end % \par % \begin{markdown} % +%#### HTML elements +% If the \Opt{html} option is enabled and we are using [\TeX{}4ht][1], we will +% pass HTML elements to the output HTML document unchanged. +% +% [1]: https://tug.org/tex4ht/ +% +% \end{markdown} +% \begin{macrocode} +\@ifundefined{HCode}{}{ + \markdownSetup{ + rendererPrototypes = { + inlineHtmlTag = {% + \ifvmode + \IgnorePar + \EndP + \fi + \HCode{#1}% + }, + inputBlockHtmlElement = {% + \ifvmode + \IgnorePar + \fi + \EndP + \special{t4ht*<#1}% + \par + \ShowPar + }, + }, + } +} +% \end{macrocode} +% \par +% \begin{markdown} +% %#### Citations % Here is a basic implementation for citations that uses the \LaTeX{} \mref{cite} % macro. There are also implementations that use the \pkg{natbib} \mref{citep}, @@ -20650,20 +21296,44 @@ end %#### Links % 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. -% +% mistaken for a parameter character. % \end{markdown} % \begin{macrocode} \RequirePackage{url} -\def\markdownRendererLinkPrototype{% +\RequirePackage{expl3} +\ExplSyntaxOn +\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} + \def\next##1##2##3##4{ + \endgroup +% \end{macrocode} +% \begin{markdown} +% If the URL begins with a hash sign, then we assume that it is a relative +% reference. Otherwise, we assume that it is an absolute URL. +% \end{markdown} +% \begin{macrocode} + \tl_set:Nx + \l_tmpa_tl + { \str_range:nnn { ##3 } { 1 } { 1 } } + \str_if_eq:NNTF + \l_tmpa_tl + \c_hash_str + { + \exp_args:No + \markdownLaTeXRendererRelativeLink + { \str_range:nnn { ##3 } { 2 } { -1 } } + }{ + \markdownLaTeXRendererAbsoluteLink { ##1 } { ##2 } { ##3 } { ##4 } + } + } + \next +} +\ExplSyntaxOff +\def\markdownLaTeXRendererAbsoluteLink#1#2#3#4{% + #1\footnote{\ifx\empty#4\empty\else#4: \fi\texttt<\url{#3}\texttt>}} +\def\markdownLaTeXRendererRelativeLink#1{% + \ref{#1}} % \end{macrocode} % \par % \begin{markdown} @@ -20681,14 +21351,16 @@ end \newtoks\markdownLaTeXTable \newtoks\markdownLaTeXTableAlignment \newtoks\markdownLaTeXTableEnd -\@ifpackageloaded{booktabs}{ - \let\markdownLaTeXTopRule\toprule - \let\markdownLaTeXMidRule\midrule - \let\markdownLaTeXBottomRule\bottomrule -}{ - \let\markdownLaTeXTopRule\hline - \let\markdownLaTeXMidRule\hline - \let\markdownLaTeXBottomRule\hline +\AtBeginDocument{% + \@ifpackageloaded{booktabs}{% + \def\markdownLaTeXTopRule{\toprule}% + \def\markdownLaTeXMidRule{\midrule}% + \def\markdownLaTeXBottomRule{\bottomrule}% + }{% + \def\markdownLaTeXTopRule{\hline}% + \def\markdownLaTeXMidRule{\hline}% + \def\markdownLaTeXBottomRule{\hline}% + }% } \markdownSetup{rendererPrototypes={ table = {% @@ -20755,17 +21427,12 @@ end % \par % \begin{markdown} % -%#### YAML Metadata -% \label{sec:latexyamlmetadata} -% To parse the \acro{yaml} metadata we will use the expl3 language from the -% \LaTeX3 kernel. +%#### YAML Metadata {#latexyamlmetadata} % % \end{markdown} % \begin{macrocode} -\RequirePackage{expl3} \ExplSyntaxOn % \end{macrocode} -% \par % \begin{markdown} % % To keep track of the current type of structure we inhabit when we are @@ -21079,9 +21746,9 @@ end % \par % \begin{markdown} % -% \Hologo{ConTeXt} Implementation -%-------------------------------- -% \label{sec:contextimplementation} +% \Hologo{ConTeXt} Implementation {#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 % *seem* to implement (the documentation is scarce) the majority of the @@ -21090,7 +21757,7 @@ end % after supplying the missing plain \TeX{} macros. % % The \Hologo{ConTeXt} implementation redefines the plain \TeX{} logging macros -% (see Section \vref{sec:texinterfacelogging}) to use the \Hologo{ConTeXt} +% (see Section <#sec:texinterfacelogging>) to use the \Hologo{ConTeXt} % \mref{writestatus} macro. % % \end{markdown} @@ -21219,7 +21886,7 @@ end \markdownInput{#3}% \fi}% \def\markdownRendererImagePrototype#1#2#3#4{% - \placefigure[][fig:#1]{#4}{\externalfigure[#3]}}% + \placefigure[][]{#4}{\externalfigure[#3]}}% \def\markdownRendererUlBeginPrototype{\startitemize}% \def\markdownRendererUlBeginTightPrototype{\startitemize[packed]}% \def\markdownRendererUlItemPrototype{\item}% |