pandoc LaTeX 数学公式转 Typst标签label提取与迁移实战指南【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文围绕 pandoc 将 LaTeX 数学环境转换为 Typst 输出时对公式标签\label的处理展开以仓库命令测试 test/command/10805.md 为切入点剖析 Typst 写入器 src/Text/Pandoc/Writers/Typst.hs 中extractLabel与toLabel的实现细节说明\label如何被转换为 Typst 的...标签或#label(...)函数调用并给出可复制的实战命令。读完本文你将掌握 LaTeX 公式中带标签方程迁移到 Typst 的完整行为以及标签含空格、标点等特殊字符时的处理规则与底层原理。背景从 LaTeX equation 到 Typst 公式pandoc 是一个通用文档转换器其 Typst 写入器位于 src/Text/Pandoc/Writers/Typst.hs。当输入是 LaTeX 文档中的数学公式时pandoc 通过Math块处理内部调用convertMath TM.writeTypst将 TeX 数学表达式翻译为 Typst 语法见 Math 分支InlineMath输出为$ ... $DisplayMath输出为$ ... $两侧带空格在这一转换过程中LaTeX 公式里常见的\label{eq:U}会被单独提取出来转换成 Typst 可识别的标签结构这正是命令测试 10805 所覆盖的场景。测试用例 10805标签行为的验收标准命令测试文件 test/command/10805.md 包含两个输入输出对它们直接定义了LaTeX 公式标签转 Typst的期望行为。用例一普通标签\label{eq:U}% pandoc -t typst -f latex \begin{equation} \label{eq:U} U A \end{equation} ^D $ U A $eq:U输入LaTeX 的equation环境内含\label{eq:U}与公式U A输出$ U A $eq:U结论当标签内容是合法 Typst 标识符由字母、数字、下划线、连字符、点、冒号等组成时pandoc 会把它渲染成 Typst 的独立标签语法eq:U紧跟在公式块之后。用例二含空格的标签\label{eq:U 2}% pandoc -t typst -f latex \begin{equation} \label{eq:U 2} U A \end{equation} ^D $ U A $#label(eq:U 2)输入标签标识符eq:U 2中包含空格输出$ U A $#label(eq:U 2)结论当标签无法作为裸标签使用时pandoc 自动降级为调用 Typst 的#label(...)函数并加引号包裹保证空格等特殊字符不会破坏 Typst 语法。源码剖析标签提取与输出的两条路径标签提取extractLabel写入器在处理Math节点时会先调用extractLabel从 LaTeX 源码字符串中扫描标签见 extractLabel 定义extractLabel :: Text - Maybe Text extractLabel go . T.unpack where go [] Nothing go (\\:l:a:b:e:l:{:xs) Just (T.pack (takeWhile (/}) xs)) go (_:xs) go xs其核心逻辑为逐字符扫描数学源码命中字面序列\label{后取出直到第一个}之间的内容作为标签文本未找到则返回Nothing公式照常输出且不带任何标签。从实现看它只识别小写\label{...}形式\label后若紧跟空格或其他分隔符则不会被识别。标签提取成功后toLabel再决定输出形式。标签输出toLabel与LabelTypetoLabel是决定裸标签还是函数调用的分水岭见 toLabel 定义data LabelType FreestandingLabel | ArgumentLabel deriving (Show, Eq) toLabel :: LabelType - Text - Doc Text toLabel labelType ident | T.null ident mempty | T.all isIdentChar ident literal ident | otherwise case labelType of FreestandingLabel - #label parens (doubleQuoted ident) ArgumentLabel - label parens (doubleQuoted ident) where ident T.pack $ unEscapeString $ T.unpack ident isIdentChar :: Char - Bool isIdentChar c isXIDContinue c || c _ || c - || c . || c :规则可以总结为条件输出形式说明标签为空字符串不输出直接返回空文档标签全部由isIdentChar允许的字符组成标识符Typst 独立标签语法如eq:U标签含空格等非法字符#label(标识符)降级为函数调用 字符串引号包裹其中isIdentChar允许的字符集合为Unicode 的 XID_Continue 字符字母、数字等、_、-、.、:。这正是用例一eq:U冒号与字母均合法与用例二#label(eq:U 2)空格不合法输出不同的根源。另外extractLabel提取出的标签在toLabel中会先经过unEscapeString反转义因此 LaTeX 中的转义序列如\_会被还原为普通字符后再做合法性判断。公式标签输出的组合逻辑公式与标签的组合发生在Math分支见 Math 分支实现Math mathType str - do res - convertMath TM.writeTypst mathType str case res of Left il - inlineToTypst il Right r - (case extractLabel str of -- #10805 Nothing - id Just lab - ( (toLabel FreestandingLabel lab))) $ case mathType of InlineMath - return $ $ literal r $ DisplayMath - return $ $ literal r $关键点转换成功路径Right r先按InlineMath/DisplayMath生成 Typst 公式再用extractLabel探测标签若提取到标签就通过把toLabel FreestandingLabel lab的结果拼接在公式之后。转换失败路径Left ilTeXMath 无法翻译时回退到inlineToTypst此时不附加任何标签。标签位置输出顺序是公式 标签与测试 10805 的期望输出完全一致$ U A $eq:U、$ U A $#label(eq:U 2)。FreestandingLabel这一标签类型意味着输出的是独立的...或#label(...)结构可用于后续eq:U形式的引用。实战在命令行中验证直接在当前仓库执行测试 10805 对应的命令即可复现以下命令以仓库根目录为工作目录# 用例一合法标识符标签 → 裸标签 printf \\begin{equation}\n \\label{eq:U}\n U A\n\\end{equation}\n | pandoc -t typst -f latex # 用例二含空格标签 → #label 函数 printf \\begin{equation}\n \\label{eq:U 2}\n U A\n\\end{equation}\n | pandoc -t typst -f latex第一条命令应输出$ U A $eq:U第二条应输出$ U A $#label(eq:U 2)与 test/command/10805.md 中的 golden 结果一致。这也说明只要 LaTeX 公式内使用\label{...}pandoc 的 Typst 输出就会自动携带可引用的标签无需手工追加。相关实现与延伸阅读标签机制不仅用于数学公式Typst 写入器在标题、表格等场景也复用toLabel例如标题通过typst-label键或自动生成的ident生成标签见 Header 处理表格也支持typst-label自定义标签。此外toLabel的ArgumentLabel分支用于#cite(...)等函数参数位置的标签输出见 toCite 实现形成一套统一的标签输出体系裸标签id用于引用id、id指向目标#label(id)处理无法作为裸标识符的字符串标签#cite(...)内嵌label(...)用于引用书目条目如需进一步了解 Typst 输出整体行为可继续阅读 src/Text/Pandoc/Writers/Typst.hs 与 doc/typst-property-output.md介绍 Typst 属性输出机制以及 test/command/11090.mdTypst 相关命令测试。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandoc LaTeX 数学公式转 Typst：标签（label）提取与迁移实战指南
pandoc LaTeX 数学公式转 Typst标签label提取与迁移实战指南【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文围绕 pandoc 将 LaTeX 数学环境转换为 Typst 输出时对公式标签\label的处理展开以仓库命令测试 test/command/10805.md 为切入点剖析 Typst 写入器 src/Text/Pandoc/Writers/Typst.hs 中extractLabel与toLabel的实现细节说明\label如何被转换为 Typst 的...标签或#label(...)函数调用并给出可复制的实战命令。读完本文你将掌握 LaTeX 公式中带标签方程迁移到 Typst 的完整行为以及标签含空格、标点等特殊字符时的处理规则与底层原理。背景从 LaTeX equation 到 Typst 公式pandoc 是一个通用文档转换器其 Typst 写入器位于 src/Text/Pandoc/Writers/Typst.hs。当输入是 LaTeX 文档中的数学公式时pandoc 通过Math块处理内部调用convertMath TM.writeTypst将 TeX 数学表达式翻译为 Typst 语法见 Math 分支InlineMath输出为$ ... $DisplayMath输出为$ ... $两侧带空格在这一转换过程中LaTeX 公式里常见的\label{eq:U}会被单独提取出来转换成 Typst 可识别的标签结构这正是命令测试 10805 所覆盖的场景。测试用例 10805标签行为的验收标准命令测试文件 test/command/10805.md 包含两个输入输出对它们直接定义了LaTeX 公式标签转 Typst的期望行为。用例一普通标签\label{eq:U}% pandoc -t typst -f latex \begin{equation} \label{eq:U} U A \end{equation} ^D $ U A $eq:U输入LaTeX 的equation环境内含\label{eq:U}与公式U A输出$ U A $eq:U结论当标签内容是合法 Typst 标识符由字母、数字、下划线、连字符、点、冒号等组成时pandoc 会把它渲染成 Typst 的独立标签语法eq:U紧跟在公式块之后。用例二含空格的标签\label{eq:U 2}% pandoc -t typst -f latex \begin{equation} \label{eq:U 2} U A \end{equation} ^D $ U A $#label(eq:U 2)输入标签标识符eq:U 2中包含空格输出$ U A $#label(eq:U 2)结论当标签无法作为裸标签使用时pandoc 自动降级为调用 Typst 的#label(...)函数并加引号包裹保证空格等特殊字符不会破坏 Typst 语法。源码剖析标签提取与输出的两条路径标签提取extractLabel写入器在处理Math节点时会先调用extractLabel从 LaTeX 源码字符串中扫描标签见 extractLabel 定义extractLabel :: Text - Maybe Text extractLabel go . T.unpack where go [] Nothing go (\\:l:a:b:e:l:{:xs) Just (T.pack (takeWhile (/}) xs)) go (_:xs) go xs其核心逻辑为逐字符扫描数学源码命中字面序列\label{后取出直到第一个}之间的内容作为标签文本未找到则返回Nothing公式照常输出且不带任何标签。从实现看它只识别小写\label{...}形式\label后若紧跟空格或其他分隔符则不会被识别。标签提取成功后toLabel再决定输出形式。标签输出toLabel与LabelTypetoLabel是决定裸标签还是函数调用的分水岭见 toLabel 定义data LabelType FreestandingLabel | ArgumentLabel deriving (Show, Eq) toLabel :: LabelType - Text - Doc Text toLabel labelType ident | T.null ident mempty | T.all isIdentChar ident literal ident | otherwise case labelType of FreestandingLabel - #label parens (doubleQuoted ident) ArgumentLabel - label parens (doubleQuoted ident) where ident T.pack $ unEscapeString $ T.unpack ident isIdentChar :: Char - Bool isIdentChar c isXIDContinue c || c _ || c - || c . || c :规则可以总结为条件输出形式说明标签为空字符串不输出直接返回空文档标签全部由isIdentChar允许的字符组成标识符Typst 独立标签语法如eq:U标签含空格等非法字符#label(标识符)降级为函数调用 字符串引号包裹其中isIdentChar允许的字符集合为Unicode 的 XID_Continue 字符字母、数字等、_、-、.、:。这正是用例一eq:U冒号与字母均合法与用例二#label(eq:U 2)空格不合法输出不同的根源。另外extractLabel提取出的标签在toLabel中会先经过unEscapeString反转义因此 LaTeX 中的转义序列如\_会被还原为普通字符后再做合法性判断。公式标签输出的组合逻辑公式与标签的组合发生在Math分支见 Math 分支实现Math mathType str - do res - convertMath TM.writeTypst mathType str case res of Left il - inlineToTypst il Right r - (case extractLabel str of -- #10805 Nothing - id Just lab - ( (toLabel FreestandingLabel lab))) $ case mathType of InlineMath - return $ $ literal r $ DisplayMath - return $ $ literal r $关键点转换成功路径Right r先按InlineMath/DisplayMath生成 Typst 公式再用extractLabel探测标签若提取到标签就通过把toLabel FreestandingLabel lab的结果拼接在公式之后。转换失败路径Left ilTeXMath 无法翻译时回退到inlineToTypst此时不附加任何标签。标签位置输出顺序是公式 标签与测试 10805 的期望输出完全一致$ U A $eq:U、$ U A $#label(eq:U 2)。FreestandingLabel这一标签类型意味着输出的是独立的...或#label(...)结构可用于后续eq:U形式的引用。实战在命令行中验证直接在当前仓库执行测试 10805 对应的命令即可复现以下命令以仓库根目录为工作目录# 用例一合法标识符标签 → 裸标签 printf \\begin{equation}\n \\label{eq:U}\n U A\n\\end{equation}\n | pandoc -t typst -f latex # 用例二含空格标签 → #label 函数 printf \\begin{equation}\n \\label{eq:U 2}\n U A\n\\end{equation}\n | pandoc -t typst -f latex第一条命令应输出$ U A $eq:U第二条应输出$ U A $#label(eq:U 2)与 test/command/10805.md 中的 golden 结果一致。这也说明只要 LaTeX 公式内使用\label{...}pandoc 的 Typst 输出就会自动携带可引用的标签无需手工追加。相关实现与延伸阅读标签机制不仅用于数学公式Typst 写入器在标题、表格等场景也复用toLabel例如标题通过typst-label键或自动生成的ident生成标签见 Header 处理表格也支持typst-label自定义标签。此外toLabel的ArgumentLabel分支用于#cite(...)等函数参数位置的标签输出见 toCite 实现形成一套统一的标签输出体系裸标签id用于引用id、id指向目标#label(id)处理无法作为裸标识符的字符串标签#cite(...)内嵌label(...)用于引用书目条目如需进一步了解 Typst 输出整体行为可继续阅读 src/Text/Pandoc/Writers/Typst.hs 与 doc/typst-property-output.md介绍 Typst 属性输出机制以及 test/command/11090.mdTypst 相关命令测试。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考