markdown (12sep17)

git-svn-id: svn://tug.org/texlive/trunk@45278 c570f23f-e606-0410-a88d-b1316a301751

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},