文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载导读pandoc 的 LaTeX 阅读器不仅要处理常规的 LaTeX 命令与环境还必须支持\newcommand等宏定义并正确理解figure等浮动环境的结构。test/command/2118.md正是这样一个端到端验证用例它在同一份 LaTeX 文档中定义了一个图片宏\inclgraph随后在figure环境中使用该宏最终期望输出一个带latex-placement属性与 80% 宽度的Figure块。本文以该测试用例为线索逐层讲解宏定义如何被捕获与展开、figure环境如何被解析为Figure块以及\includegraphics的宽度选项如何被转换为 pandoc 的内部表示让读者既能复现测试也能理解背后的实现原理。一、测试用例全景从 LaTeX 输入到 Native 输出test/command/2118.md是一个典型的 pandoc 命令测试command test文件全文只有一个代码块完整内容如下% pandoc -f latex -t native \newcommand{\inclgraph}{\includegraphics[width0.8\textwidth]} \begin{figure}[ht] \inclgraph{setminus.png} \caption{Set subtraction} \label{fig:setminus} \end{figure} ^D [ Figure ( fig:setminus , [] , [ ( latex-placement , ht ) ] ) (Caption Nothing [ Plain [ Str Set , Space , Str subtraction ] ]) [ Plain [ Image ( , [] , [ ( width , 80% ) ] ) [] ( setminus.png , ) ] ] ]测试通过pandoc -f latex -t native把 LaTeX 输入转换为 pandoc 的 NativeAST 文本表示输出。这个用例一次性覆盖了 LaTeX 阅读器中三个核心机制宏定义与展开\newcommand{\inclgraph}{...}定义了一个无参宏其展开内容是一个带可选参数的\includegraphics调用figure 浮动环境解析环境头部可选参数[ht]被提取为latex-placement属性\caption内容成为Figure块的标题\label成为块的标识符图片尺寸换算width0.8\textwidth被转换为width80%即基于\textwidth的相对宽度被换算为百分比。预期输出中Figure块由figure解析器构造标题内图片的Plain [Image ...]结构则说明阅读器会把原本包裹图片的段落层用于承载标题剥掉这正是 figure 解析器 中go (Para [Image attr [Str image] target]) Plain [Image attr [] target]这一转换规则的作用去掉Image内部的占位文本与多余的Para包装。二、命令测试的格式约定理解 2118.md 的骨架test/command/2118.md属于 pandoc 的 golden 测试体系其格式约定定义在 test/Tests/Command.hs 中第一行以%开头后面是要执行的命令行这里是pandoc -f latex -t native之后是作为标准输入传给命令的内容LaTeX 源码输入以单独一行^D结束^D之后的内容是期望的标准输出这里是 Native 格式的 AST如果还期望 stderr 输出需以2前缀放在 stdout 期望之前如果期望非零退出码最后一行应以开头跟上退出码。测试运行时runCommandTest 会把%后的命令交给execTest执行实际会替换为test-pandoc --emulate见 pandocToEmulate然后与文件中的期望输出做 golden 比较。因此 2118.md 本质上是一个可重复运行的回归测试只要 LaTeX 阅读器对宏与 figure 的处理行为发生变化该用例就会立即失败并给出 diff。三、宏定义解析\newcommand是如何被捕获的3.1 macroDef宏定义的分发入口在 LaTeX 阅读器中所有宏定义都由 src/Text/Pandoc/Readers/LaTeX/Macro.hs 模块统一处理。入口函数macroDefMacro.hs#L24-L51先通过peekTok检查下一个控制序列是否属于macroDefCommandsMacro.hs#L56-L71集合只有命中才继续解析否则快速失败、避免干扰普通命令。该集合覆盖了经典 TeX 命令\def、\gdef、\edef、\xdef、\let、\newif、\global标准 LaTeX 命令\newcommand、\renewcommand、\providecommand、\DeclareMathOperator、\DeclareRobustCommandLaTeX3/xparse 系列\NewDocumentCommand、\RenewDocumentCommand、\ProvideDocumentCommand及其可展开变体、\NewDocumentEnvironment等环境定义\newenvironment、\renewenvironment、\provideenvironment。2118.md 中的\newcommand正是由这里分发到newcommand解析器的。macroDef还有一点值得注意解析过程使用withRaw捕获原始 token 流如果latex_macros扩展被禁用guardDisabled Ext_latex_macros宏定义不会被注册到状态中但仍会以 RawBlock 形式保留原样输出。3.2 newcommand参数个数、可选参数与内容捕获newcommand解析器位于 Macro.hs#L187-L222同时处理\newcommand、\renewcommand、\providecommand、\DeclareMathOperator、\DeclareRobustCommand五种命令。其解析流程以withVerbatimMode进入逐字模式避免在定义阶段就展开宏内容宏应在使用时展开而非定义时读取被定义的控制序列名支持\foo与{\foo}两种写法也支持带星号的\newcommand*变体通过bracketedNum解析可选的参数个数[n]生成map ArgNum [1..n]的参数规格argspecs通过bracketedToks解析可选的默认参数[default]存为optarg用bracedOrToken捕获宏体contents。最终构造Macro GroupScope ExpandWhenUsed argspecs optarg contentsMacro.hs#L216ExpandWhenUsed表示延迟到使用点展开GroupScope表示作用域限于当前分组\global可提升为GlobalScope。对于 2118.md 中的\newcommand{\inclgraph}{\includegraphics[width0.8\textwidth]}宏名为inclgraph无参数numargs 0、无默认可选参数宏体是\includegraphics[width0.8\textwidth]这条 token 序列。后续遇到\inclgraph{setminus.png}时阅读器会把宏体展开为\includegraphics[width0.8\textwidth]{setminus.png}再继续解析最终落入\includegraphics的处理逻辑。这正是本测试用例的核心验证点宏定义必须在使用前被捕获且展开必须在解析普通命令之前完成。另外注意 Macro.hs#L217-L222 的重定义语义若宏已存在\providecommand静默忽略\renewcommand允许覆盖而\newcommand会输出MacroAlreadyDefined日志消息并放弃定义。四、figure 环境解析placement、caption 与 label 的归宿4.1 figure 解析器\begin{figure}[ht]由 LaTeX.hs#L1233-L1235 注册的命令表映射到figure解析器LaTeX.hs#L1400-L1427。figure的执行步骤poshint - option $ untokenize $ bracketedToks解析环境头部的可选参数[ht]得到字符串htresetCaption 遍历内部内容用label解析器捕获\label到sLastLabel状态用block解析器解析正文\caption会把标题写入sCaption状态从状态中取出captionsCaption与mblabelsLastLabel构造属性kvs [(latex-placement, poshint) | not (T.null poshint)]——即只有显式写了放置参数时才生成该属性这正是预期输出中(latex-placement , ht)的来源若存在\label将其登记到sLabels供\ref/\autoref交叉引用解析使用编号由sLastFigureNum维护最终return $ B.figureWith attr caption content构造Figure块。所以 2118.md 期望输出中的Figure (fig:setminus, [], [(latex-placement, ht)])三个字段分别来自\label的标识符、空的 classes、[ht]放置参数。latex-placement属性在后续通过 LaTeX 写入器输出时会还原为\begin{figure}[ht]实现转换的往返保真。4.2 caption 的归一化\caption{Set subtraction}的标题文本经阅读器解析后成为Caption Nothing [Plain [Str Set, Space, Str subtraction]]——短标题参数[...]空缺时为Nothing。注意图片本身不再重复包含标题文字figure中的go函数会把Para [Image attr [Str image] target]改写为Plain [Image attr [] target]即删除图片内部的占位Str image文本因为标题已经由Caption承载LaTeX.hs#L1424-L1427。五、\includegraphics 与尺寸换算0.8\textwidth 如何变成 80%宏展开后\includegraphics[width0.8\textwidth]{setminus.png}由 LaTeX.hs#L451-L453 处理(includegraphics, do options - option [] keyvals src - bracedFilename mkImage options . unescapeURL $ src)keyvals解析[width0.8\textwidth]得到[(width, 0.8\\textwidth)]随后交给mkImageLaTeX.hs#L245-L257。mkImage的关键逻辑Just (num, \\textwidth) - (k, showFl (num * 100) %) Just (num, \\linewidth) - (k, showFl (num * 100) %)当宽高值是\textwidth或\linewidth的倍数时0.8 * 100 80得到width80%随后只保留width与height两个键。这解释了预期输出中的Image (, [], [(width, 80%)]) [] (setminus.png, )一个无标识符、无 classes、带 80% 宽度属性的图片指向setminus.png。此外还支持\columnwidth、\paperwidth等同类相对单位换算为百分比以及height键的同类处理非相对单位如width5cm则直接保留原始值。六、实战演练与扩展6.1 复现测试在构建好 pandoc 后进入test/command/目录该测试的工作目录约定将 2118.md 中的 LaTeX 部分存为输入文件执行pandoc -f latex -t native input.tex即可得到与^D之后完全一致的 Native 输出也可以通过项目测试框架单独运行该用例cabal test pandoc --test-options-p Command-p Command会运行 Tests.Command.tests 注册的所有命令测试每个test/command/*.md对应一个用例2118 即其中之一这是验证宏与 figure 行为的最佳回归手段。6.2 常见变体带参宏、可选参数与 renewcommand将 2118 的思路推广LaTeX 阅读器对以下写法同样支持对应newcommand解析器的参数处理% 带一个必选参数与一个默认可选参数 \newcommand{\mypic}[2][0.5]{\includegraphics[width#1\textwidth]{#2}} % 覆盖已有定义 \renewcommand{\inclgraph}[1]{\includegraphics[width0.9\linewidth]{#1}}其中[n]声明参数个数并生成ArgNum 1..n规格[default]提供可选参数默认值宏体内可用#1、#2引用参数。使用点的解析会先按参数规格抓取参数再做宏体展开最后才交给普通命令解析器。6.3 注意事项宏必须在使用之前定义宏定义与figure环境一样受latex_macros扩展控制可通过-f latexlatex_macros显式启用默认启用\graphicspath会通过setResourcePath追加资源搜索路径LaTeX.hs#L1437-L1442转换含相对路径图片的文档时可用于调整查找目录Figure块与latex-placement属性是 LaTeX 阅读/写出往返的桥梁LaTeX 写入器会依据latex-placement还原\begin{figure}[...]保证转换不丢失浮动放置语义。结语test/command/2118.md虽小却串联起 LaTeX 阅读器中宏定义捕获Macro.hs、宏体展开、figure 环境解析、caption/label 状态管理以及图片尺寸归一化LaTeX.hs整条链路。阅读它等于同时读懂了 pandoc 处理 LaTeX 浮动体与自定义宏的两套核心机制需要继续深入时可以对照 Tests.Command 的 golden 测试框架在test/command/目录下找到更多覆盖不同语法的同类用例。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐Pandoc LaTeX 读取器对原始 TeX 的宏解析与展开机制基于 test/command/3983.md 的深入剖析Pandoc LaTeX 读取器对原始 TeX 的宏解析与展开机制基于 test/command/3983.md 的深入剖析 本文以仓库中的命令行回归测试用例文档开发工具CLIPandoc LaTeX 读取器如何解析 etoolbox 开关宏从 test/command/3853.md 理解 \newtoggle 与 \iftogglePandoc LaTeX 读取器如何解析 etoolbox 开关宏从 test/command/3853.md 理解 \newtoggle 与 \iftogg文档开发工具CLIPandoc LaTeX 读取器的 \include 跨文件解析与宏展开机制——golden test 3971 源码级剖析Pandoc LaTeX 读取器的 \include 跨文件解析与宏展开机制——golden test 3971 源码级剖析 导读pandoc 在将 LaTe文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
