From 78cc5f15a2679016b4fc8dc5948a5575276c7637 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 12 Sep 2017 22:15:30 +0000 Subject: markdown (12sep17) git-svn-id: svn://tug.org/texlive/trunk@45278 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/generic/markdown/markdown.dtx | 229 ++++++++++++++------- 1 file changed, 153 insertions(+), 76 deletions(-) (limited to 'Master/texmf-dist/source/generic') 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 % @@ -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}, -- cgit v1.2.3