summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/generic
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-09-12 22:15:30 +0000
committerKarl Berry <karl@freefriends.org>2017-09-12 22:15:30 +0000
commit78cc5f15a2679016b4fc8dc5948a5575276c7637 (patch)
treebaa7e5db65807a142d2b580874c79f5ec927ea54 /Master/texmf-dist/source/generic
parentc60e6aec42350f5b0661a63053ab977e8540ce59 (diff)
markdown (12sep17)
git-svn-id: svn://tug.org/texlive/trunk@45278 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/generic')
-rw-r--r--Master/texmf-dist/source/generic/markdown/markdown.dtx229
1 files changed, 153 insertions, 76 deletions
diff --git a/Master/texmf-dist/source/generic/markdown/markdown.dtx b/Master/texmf-dist/source/generic/markdown/markdown.dtx
index e0595966a24..406029330ea 100644
--- a/Master/texmf-dist/source/generic/markdown/markdown.dtx
+++ b/Master/texmf-dist/source/generic/markdown/markdown.dtx
@@ -156,7 +156,7 @@
% \fi
% \begin{macrocode}
local metadata = {
- version = "2.5.3",
+ version = "2.5.4",
comment = "A module for the conversion from markdown to plain TeX",
author = "John MacFarlane, Hans Hagen, Vít Novotný",
copyright = "2009-2017 John MacFarlane, Hans Hagen; " ..
@@ -230,7 +230,7 @@ local md5 = require("md5")
% \subsubsection{Plain \TeX{} Prerequisites}\label{sec:texprerequisites}
% The plain \TeX{} part of the package requires that the plain \TeX{}
% format (or its superset) is loaded, all the Lua prerequisites (see
-% Section \ref{sec:luaprerequisites}) and the following Lua module:
+% Section \ref{sec:luaprerequisites}), and the following Lua module:
% \begin{description}
% \item[\pkg{Lua File System}] A library that provides access to the
% filesystem via \acro{os}-specific syscalls. It is used by the plain
@@ -250,17 +250,10 @@ local md5 = require("md5")
% \m{directlua} primitive or the shell access file stream 18 is available in
% your \TeX{} engine. If only the shell access file stream is available in your
% \TeX{} engine (as is the case with \hologo{pdfTeX} and \Hologo{XeTeX}) or if
-% you enforce the use of shell using the \m{markdownMode} macro, then note the
-% following:
-% \begin{itemize}
-% \item Unless your \TeX{} engine is globally configured to enable shell
-% access, you will need to provide the \t`-shell-escape` parameter to your
-% engine when typesetting a document.
-% \item You will need to avoid the use of the \t`-output-directory` \TeX{}
-% parameter when typesetting a document. The parameter causes auxiliary
-% files to be written to a specified output directory, but the shell will
-% be executed in the current directory. Things will not work out.
-% \end{itemize}
+% you enforce the use of shell using the \m{markdownMode} macro, then note that
+% unless your \TeX{} engine is globally configured to enable shell access, you
+% will need to provide the \t`-shell-escape` parameter to your engine when
+% typesetting a document.
%
% \iffalse
%</tex>
@@ -279,13 +272,22 @@ local md5 = require("md5")
% This package is used to provide the \m{markdownSetup} macro, the package
% options processing, as well as the parameters of the \envm{markdown*}
% \LaTeX{} environment.
+% \begin{macrocode}
+\RequirePackage{keyval}
+% \end{macrocode}
% \item[\pkg{url}] A package that provides the \m{url} macro for the
% typesetting of \acro{url}s. It is used to provide the default token renderer
% prototype (see Section \ref{sec:texrendererprototypes}) for links.
+% \begin{macrocode}
+\RequirePackage{url}
+% \end{macrocode}
% \item[\pkg{graphicx}] A package that provides the \m{includegraphics} macro for
% the typesetting of images. It is used to provide the corresponding
% default token renderer prototype (see Section
% \ref{sec:texrendererprototypes}).
+% \begin{macrocode}
+\RequirePackage{graphicx}
+% \end{macrocode}
% \item[\pkg{paralist}] A package that provides the \envm{compactitem},
% \envm{compactenum}, and \envm{compactdesc} macros for the
% typesetting of tight bulleted lists, ordered lists, and definition lists.
@@ -294,13 +296,22 @@ local md5 = require("md5")
% \item[\pkg{ifthen}] A package that provides a concise syntax for the
% inspection of macro values. It is used to determine whether or not the
% \pkg{paralist} package should be loaded based on the user options.
+% \begin{macrocode}
+\RequirePackage{ifthen}
+% \end{macrocode}
% \item[\pkg{fancyvrb}] A package that provides the \m{VerbatimInput} macros
% for the verbatim inclusion of files containing code. It is used to
% provide the corresponding default token renderer prototype (see Section
% \ref{sec:texrendererprototypes}).
+% \begin{macrocode}
+\RequirePackage{fancyvrb}
+% \end{macrocode}
% \item[\pkg{csvsimple}] A package that provides the default token renderer
% prototype for iA\,Writer content blocks with the \acro{csv} filename
% extension (see Section \ref{sec:texrendererprototypes}).
+% \begin{macrocode}
+\RequirePackage{csvsimple}
+% \end{macrocode}
% \end{description}
%
% \iffalse
@@ -310,7 +321,8 @@ local md5 = require("md5")
% \subsubsection{\Hologo{ConTeXt} prerequisites}
% The \Hologo{ConTeXt} part of the package requires that either the Mark II or
% the Mark IV format is loaded, all the plain \TeX{} prerequisites (see
-% Section \ref{sec:texprerequisites}), and the following modules:
+% Section \ref{sec:texprerequisites}), and the following \Hologo{ConTeXt}
+% modules:
% \begin{description}
% \item[\pkg{m-database}] A module that provides the default token renderer
% prototype for iA\,Writer content blocks with the \acro{csv} filename
@@ -367,6 +379,34 @@ local M = {}
% \begin{macrocode}
local defaultOptions = {}
% \end{macrocode}
+% \pagebreak
+% \paragraph{File and Directory Names}
+% \begin{optionlist}
+% \Valitem[.]{cacheDir}{path}
+% A path to the directory containing auxiliary cache files. It is
+% considered sane to set the path to a subdirectory of \t`outputDir`.
+% If the last segment of the path does not exist, it will be created by the
+% plain \TeX, \LaTeX, and \Hologo{ConTeXt} implementations. The Lua
+% implementation expects that the entire path already exists.
+%
+% When iteratively writing and typesetting a markdown document, the cache
+% files are going to accumulate over time. You are advised to clean the
+% cache directory every now and then, or to set it to a temporary filesystem
+% (such as \t`/tmp` on \acro{un*x} systems), which gets periodically
+% emptied.
+% \begin{macrocode}
+defaultOptions.cacheDir = "."
+% \end{macrocode}
+%
+% \Valitem[.]{outputDir}{path}
+% A path to the directory containing output files. The path must be set
+% to the same value as the \t`-output-directory` option of your \TeX\
+% engine for the package to function correctly.
+% \begin{macrocode}
+defaultOptions.outputDir = "."
+% \end{macrocode}
+% \end{optionlist}
+% \paragraph{Parser Options}
% \begin{optionlist}
% \Optitem[false]{blankBeforeBlockquote}{\opt{true}, \opt{false}}
% \begin{valuelist}
@@ -410,18 +450,6 @@ defaultOptions.blankBeforeHeading = false
defaultOptions.breakableBlockquotes = false
% \end{macrocode}
%
-% \Valitem[.]{cacheDir}{directory name}
-% The path to the directory containing auxiliary cache files.
-%
-% When iteratively writing and typesetting a markdown document, the cache
-% files are going to accumulate over time. You are advised to clean the
-% cache directory every now and then, or to set it to a temporary filesystem
-% (such as \t`/tmp` on \acro{un*x} systems), which gets periodically
-% emptied.
-% \begin{macrocode}
-defaultOptions.cacheDir = "."
-% \end{macrocode}
-%
% \Optitem[false]{citationNbsps}{\opt{true}, \opt{false}}
% \begin{valuelist}
% \item[true] Replace regular spaces with non-breakable spaces inside the
@@ -719,8 +747,8 @@ defaultOptions.underscores = true
% \ref{sec:luaoptions}) used during the conversion from markdown to plain
% \TeX{}, and for changing the way markdown the tokens are rendered.
% \begin{macrocode}
-\def\markdownLastModified{2017/05/07}%
-\def\markdownVersion{2.5.3}%
+\def\markdownLastModified{2017/09/12}%
+\def\markdownVersion{2.5.4}%
% \end{macrocode}
%
% The plain \TeX{} interface is implemented by the \t`markdown.tex` file that
@@ -807,7 +835,7 @@ defaultOptions.underscores = true
% \ref{sec:luaoptions}), while some of them are specific to the plain \TeX{}
% interface.
%
-% \paragraph{File and directory names}
+% \paragraph{File and Directory names}
% The \mdef{markdownOptionHelperScriptFileName} macro sets the filename of the
% helper Lua script file that is created during the conversion from markdown to
% plain \TeX{} in \TeX{} engines without the \m{directlua} primitive. It
@@ -823,22 +851,32 @@ defaultOptions.underscores = true
%
% The \mdef{markdownOptionInputTempFileName} macro sets the filename of the
% temporary input file that is created during the conversion from markdown to
-% plain \TeX{} in \TeX{} engines without the \m{directlua} primitive. It
-% defaults to \m{jobname}\t`.markdown.out`. The same limitations as in
-% the case of the \m{markdownOptionHelperScriptFileName} macro apply here.
+% plain \TeX{} in \m{markdownMode} other than \t`2`. It defaults to
+% \m{jobname}\t`.markdown.out`. The same limitations as in the case of the
+% \m{markdownOptionHelperScriptFileName} macro apply here.
% \begin{macrocode}
\def\markdownOptionInputTempFileName{\jobname.markdown.in}%
% \end{macrocode}
%
% The \mdef{markdownOptionOutputTempFileName} macro sets the filename of the
% temporary output file that is created during the conversion from markdown to
-% plain \TeX{} in \TeX{} engines without the \m{directlua} primitive. It
-% defaults to \m{jobname}\t`.markdown.out`. The same limitations apply here as
-% in the case of the \m{markdownOptionHelperScriptFileName} macro.
+% plain \TeX{} in \m{markdownMode} other than \t`2`. It defaults to
+% \m{jobname}\t`.markdown.out`. The same limitations apply here as in the case
+% of the \m{markdownOptionHelperScriptFileName} macro.
% \begin{macrocode}
\def\markdownOptionOutputTempFileName{\jobname.markdown.out}%
% \end{macrocode}
%
+% The \mdef{markdownOptionErrorTempFileName} macro sets the filename of the
+% temporary output file that is created when a Lua error is encountered during
+% the conversion from markdown to plain \TeX{} in \m{markdownMode} other than
+% \t`2`. It defaults to \m{jobname}\t`.markdown.err`. The same limitations
+% apply here as in the case of the \m{markdownOptionHelperScriptFileName}
+% macro.
+% \begin{macrocode}
+\def\markdownOptionErrorTempFileName{\jobname.markdown.err}%
+% \end{macrocode}
+%
% The \mdef{markdownOptionCacheDir} macro corresponds to the Lua interface
% \Opt{cacheDir} option that sets the name of the directory that will contain
% the produced cache files. The option defaults to \t`_markdown_`\m{jobname},
@@ -846,7 +884,16 @@ defaultOptions.underscores = true
% package. The same limitations apply here as in the case of the
% \m{markdownOptionHelperScriptFileName} macro.
% \begin{macrocode}
-\def\markdownOptionCacheDir{./_markdown_\jobname}%
+\def\markdownOptionCacheDir{\markdownOptionOutputDir/_markdown_\jobname}%
+% \end{macrocode}
+%
+% The \mdef{markdownOptionOutputDir} macro corresponds to the Lua interface
+% \Opt{outputDir} option that sets the name of the directory that will contain
+% the produced cache files. The option defaults to \t`.`. The same limitations
+% apply here as in the case of the \m{markdownOptionHelperScriptFileName}
+% macro.
+% \begin{macrocode}
+\def\markdownOptionOutputDir{.}%
% \end{macrocode}
%
% \paragraph{Lua Interface Options}
@@ -1594,13 +1641,18 @@ defaultOptions.underscores = true
% The following options map directly to the option macros exposed by the plain
% \TeX{} interface (see Section \ref{sec:texoptions}).
% \begin{macrocode}
-\RequirePackage{keyval}
\define@key{markdownOptions}{helperScriptFileName}{%
\def\markdownOptionHelperScriptFileName{#1}}%
\define@key{markdownOptions}{inputTempFileName}{%
\def\markdownOptionInputTempFileName{#1}}%
\define@key{markdownOptions}{outputTempFileName}{%
\def\markdownOptionOutputTempFileName{#1}}%
+\define@key{markdownOptions}{errorTempFileName}{%
+ \def\markdownOptionErrorTempFileName{#1}}%
+\define@key{markdownOptions}{cacheDir}{%
+ \def\markdownOptionCacheDir{#1}}%
+\define@key{markdownOptions}{outputDir}{%
+ \def\markdownOptionOutputDir{#1}}%
\define@key{markdownOptions}{blankBeforeBlockquote}[true]{%
\def\markdownOptionBlankBeforeBlockquote{#1}}%
\define@key{markdownOptions}{blankBeforeCodeFence}[true]{%
@@ -1609,8 +1661,6 @@ defaultOptions.underscores = true
\def\markdownOptionBlankBeforeHeading{#1}}%
\define@key{markdownOptions}{breakableBlockquotes}[true]{%
\def\markdownOptionBreakableBlockquotes{#1}}%
-\define@key{markdownOptions}{cacheDir}{%
- \def\markdownOptionCacheDir{#1}}%
\define@key{markdownOptions}{citations}[true]{%
\def\markdownOptionCitations{#1}}%
\define@key{markdownOptions}{citationNbsps}[true]{%
@@ -4365,9 +4415,9 @@ return M
% \subsubsection{Logging Facilities}\label{sec:texinterfacelogging}
% \begin{macrocode}
\def\markdownInfo#1{%
- \message{(l.\the\inputlineno) markdown.tex info: #1.}}%
+ \immediate\write-1{(l.\the\inputlineno) markdown.tex info: #1.}}%
\def\markdownWarning#1{%
- \message{(l.\the\inputlineno) markdown.tex warning: #1}}%
+ \immediate\write16{(l.\the\inputlineno) markdown.tex warning: #1}}%
\def\markdownError#1#2{%
\errhelp{#2.}%
\errmessage{(l.\the\inputlineno) markdown.tex error: #1}}%
@@ -4459,9 +4509,7 @@ return M
\ifx\markdownOptionBreakableBlockquotes\undefined\else
breakableBlockquotes = \markdownOptionBreakableBlockquotes,
\fi
-\ifx\markdownOptionCacheDir\undefined\else
cacheDir = "\markdownOptionCacheDir",
-\fi
\ifx\markdownOptionCitations\undefined\else
citations = \markdownOptionCitations,
\fi
@@ -4499,6 +4547,7 @@ return M
\ifx\markdownOptionInlineFootnotes\undefined\else
inlineFootnotes = \markdownOptionInlineFootnotes,
\fi
+ outputDir = "\markdownOptionOutputDir",
\ifx\markdownOptionPreserveTabs\undefined\else
preserveTabs = \markdownOptionPreserveTabs,
\fi
@@ -4541,15 +4590,12 @@ local convert = md.new(\markdownLuaOptions)
% \end{macrocode}
%
% \subsubsection{Buffering Markdown Input}
-% The macro \mdef{markdownLuaExecuteFileStream} contains the number of the output
-% file stream that will be used to store the helper Lua script in the file named
-% \m{markdownOptionHelperScriptFileName} during the expansion of the macro
-% \m{markdownLuaExecute} when the Lua shell escape bridge is in use, and to
-% store the markdown input in the file named
-% \m{markdownOptionInputTempFileName} during the expansion of the macro
-% \m{markdownReadAndConvert}.
+% The macros \mdef{markdownInputFileStream} and \mdef{markdownOutputFileStream}
+% contain the number of the input and output file streams that will be used for
+% the IO operations of the package.
% \begin{macrocode}
-\csname newwrite\endcsname\markdownLuaExecuteFileStream
+\csname newread\endcsname\markdownInputFileStream
+\csname newwrite\endcsname\markdownOutputFileStream
% \end{macrocode}
%
% The \mdef{markdownReadAndConvertTab} macro contains the tab character literal.
@@ -4578,7 +4624,7 @@ local convert = md.new(\markdownLuaOptions)
% \end{macrocode}
% Open the \m{markdownOptionInputTempFileName} file for writing.
% \begin{macrocode}
- |immediate|openout|markdownLuaExecuteFileStream%
+ |immediate|openout|markdownOutputFileStream%
|markdownOptionInputTempFileName%
|markdownInfo{Buffering markdown input into the temporary %
input file "|markdownOptionInputTempFileName" and scanning %
@@ -4603,7 +4649,7 @@ local convert = md.new(\markdownLuaOptions)
% the \m{markdownOptionInputTempFileName} file.
% \begin{macrocode}
|ifx|relax##3|relax%
- |immediate|write|markdownLuaExecuteFileStream{##1}%
+ |immediate|write|markdownOutputFileStream{##1}%
|else%
% \end{macrocode}
% When the ending token sequence appears in the line, make the next newline
@@ -4615,7 +4661,7 @@ local convert = md.new(\markdownLuaOptions)
% \begin{macrocode}
|def^^M{%
|markdownInfo{The ending token sequence was found}%
- |immediate|closeout|markdownLuaExecuteFileStream%
+ |immediate|closeout|markdownOutputFileStream%
|endgroup%
|markdownInput|markdownOptionInputTempFileName%
#2}%
@@ -4727,34 +4773,64 @@ local convert = md.new(\markdownLuaOptions)
% engine, but it can use the \luam{print} function in the same manner it
% would use the \luam{tex.print} method.
% \begin{macrocode}
-\def\markdownLuaExecute#1{%
+\begingroup
+% \end{macrocode}
+% Swap the category code of the backslash symbol and the pipe symbol, so that
+% we may use the backslash symbol freely inside the Lua code.
+% \begin{macrocode}
+ \catcode`|=0%
+ \catcode`\\=12%
+ |gdef|markdownLuaExecute#1{%
% \end{macrocode}
% Create the file \m{markdownOptionHelperScriptFileName} and fill it with the
% input Lua code prepended with \pkg{kpathsea} initialization, so that Lua
% modules from the \TeX{} distribution are available.
% \begin{macrocode}
- \immediate\openout\markdownLuaExecuteFileStream=%
- \markdownOptionHelperScriptFileName
- \markdownInfo{Writing a helper Lua script to the file
- "\markdownOptionHelperScriptFileName"}%
- \immediate\write\markdownLuaExecuteFileStream{%
- local kpse = require('kpse')
- kpse.set_program_name('luatex') #1}%
- \immediate\closeout\markdownLuaExecuteFileStream
+ |immediate|openout|markdownOutputFileStream=%
+ |markdownOptionHelperScriptFileName
+ |markdownInfo{Writing a helper Lua script to the file
+ "|markdownOptionHelperScriptFileName"}%
+ |immediate|write|markdownOutputFileStream{%
+ local ran_ok, error = pcall(function()
+ local kpse = require('kpse')
+ kpse.set_program_name('luatex')
+ #1
+ end)
+% \end{macrocode}
+% If there was an error, use the file \m{markdownOptionErrorTempFileName} to
+% store the error message.
+% \begin{macrocode}
+ if not ran_ok then
+ local file = io.open("%
+ |markdownOptionOutputDir
+ /|markdownOptionErrorTempFileName", "w")
+ if file then
+ file:write(error .. "\n")
+ file:close()
+ end
+ print('\\markdownError{An error was encountered while executing
+ Lua code}{For further clues, examine the file
+ "|markdownOptionOutputDir
+ /|markdownOptionErrorTempFileName"}')
+ end}%
+ |immediate|closeout|markdownOutputFileStream
% \end{macrocode}
% Execute the generated \m{markdownOptionHelperScriptFileName} Lua script using
% the \TeX{}Lua binary and store the output in the
% \m{markdownOptionOutputTempFileName} file.
% \begin{macrocode}
- \markdownInfo{Executing a helper Lua script from the file
- "\markdownOptionHelperScriptFileName" and storing the result in the
- file "\markdownOptionOutputTempFileName"}%
- \markdownExecute{texlua "\markdownOptionHelperScriptFileName" >
- "\markdownOptionOutputTempFileName"}%
+ |markdownInfo{Executing a helper Lua script from the file
+ "|markdownOptionHelperScriptFileName" and storing the result in the
+ file "|markdownOptionOutputTempFileName"}%
+ |markdownExecute{texlua "|markdownOptionOutputDir
+ /|markdownOptionHelperScriptFileName" > %
+ "|markdownOptionOutputDir
+ /|markdownOptionOutputTempFileName"}%
% \end{macrocode}
% \m{input} the generated \m{markdownOptionOutputTempFileName} file.
% \begin{macrocode}
- \input\markdownOptionOutputTempFileName\relax}%
+ |input|markdownOptionOutputTempFileName|relax}%
+|endgroup
% \end{macrocode}
%
% \subsubsection{Direct Lua Access}\label{sec:directlua}
@@ -4790,6 +4866,13 @@ local convert = md.new(\markdownLuaOptions)
\catcode`\\=12%
|gdef|markdownInput#1{%
|markdownInfo{Including markdown document "#1"}%
+% \end{macrocode}
+% Attempt to open the markdown document to record it in the \t`.log` and
+% \t`.fls` files. This allows external programs such as \LaTeX Mk to track
+% changes to the markdown document.
+% \begin{macrocode}
+ |openin|markdownInputFileStream#1
+ |closein|markdownInputFileStream
|markdownLuaExecute{%
|markdownPrepare
local input = assert(io.open("#1","r")):read("*a")
@@ -4884,17 +4967,13 @@ local convert = md.new(\markdownLuaOptions)
%
% \subsubsection{Token Renderer Prototypes}
% The following configuration should be considered placeholder.
-% \begin{macrocode}
-\RequirePackage{url}
-\RequirePackage{graphicx}
-% \end{macrocode}
+%
% If the \m{markdownOptionTightLists} macro expands to \t`false`, do not load
% the \pkg{paralist} package. This is necessary for \Hologo{LaTeX2e} document
% classes that do not play nice with \pkg{paralist}, such as \pkg{beamer}.
% If the \m{markdownOptionTightLists} is undefined and the \pkg{beamer}
% document class is in use, then do not load the \pkg{paralist} package either.
% \begin{macrocode}
-\RequirePackage{ifthen}
\ifx\markdownOptionTightLists\undefined
\@ifclassloaded{beamer}{}{
\RequirePackage{paralist}}
@@ -4924,8 +5003,6 @@ local convert = md.new(\markdownLuaOptions)
olEndTight = {\markdownRendererOlEnd},
dlBeginTight = {\markdownRendererDlBegin},
dlEndTight = {\markdownRendererDlEnd}}}}
-\RequirePackage{fancyvrb}
-\RequirePackage{csvsimple}
\markdownSetup{rendererPrototypes={
lineBreak = {\\},
leftBrace = {\textbraceleft},