summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic/markdown/markdown.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/source/generic/markdown/markdown.dtx')
-rw-r--r--Master/texmf-dist/source/generic/markdown/markdown.dtx1281
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>.
% ![img](https://github.com/witiko/markdown/raw/main/markdown.png
% "The banner of the Markdown package \label{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}%