bat 中 reStructuredText 高亮测试样本实战以 reference.rst 全量参考文件为主线的 RST 语法详解【免费下载链接】batA cat(1) clone with wings.项目地址: https://gitcode.com/GitHub_Trending/ba/bat本文以 bat 仓库中的 tests/syntax-tests/source/reStructuredText/reference.rst 为主体逐节拆解这份 reStructuredText以下简称 RST全量语法参考文件覆盖的每一种标记元素——从标题、行内标记、四种列表、字面块、表格到脚注与指令并结合 bat 的语法高亮测试流水线create_highlighted_versions.py、compare_highlighted_versions.py说明这个样本文件如何为 bat 的 RST 高亮能力提供回归验证。读完后你既能把它当作一份可复制的 RST 语法手册也能理解 bat 是如何用“源文件 固定主题期望输出”的方式保证高亮结果稳定的。一、reference.rst 在 bat 测试体系中的位置bat 的高亮能力依赖其内置的语法定义集合序列化打包在 assets/syntaxes.bin 中。为验证每种语法的渲染结果稳定可复现仓库维护了一套“源样本 → 期望高亮输出”的测试资产源样本位于 tests/syntax-tests/source/每个子目录对应一种语法reStructuredText/目录下的reference.rst即本篇主体期望输出位于 tests/syntax-tests/highlighted/reStructuredText/reference.rst内容是用固定参数高亮后的带 ANSI 颜色序列的文本create_highlighted_versions.py 负责批量重新生成期望输出其固定参数为--no-config --styleplain --coloralways --themeMonokai Extended --italic-textalways脚本刻意避开“默认主题”因为默认主题可能随 macOS 外观设置变化改用--no-config与固定主题保证输出在任意环境下可比较。update.sh 与 compare_highlighted_versions.py 则分别承担“刷新基线”与“对比差异”的职责。选一份覆盖 RST 全部核心语法的参考文件作为样本非常合理只要这份文件中每类标记都得到稳定、正确的高亮RST 文件的其他典型内容也基本被覆盖。而 bat 为文件选择语式的逻辑扩展名匹配、first_line回退检测等可以在 src/syntax_mapping.rs 与 src/assets.rs 中查看高亮与输出渲染的关键路径位于 src/printer.rs。二、标题与文档结构L1–L17文件开头即示范了 RST 的标题体系 Title Subtitle --------对应规则见 reference.rst L5–L17标题由下划线或上下线构成使用的必须是可打印的非字母数字 7-bit ASCII 字符官方推荐使用的字符集是 - : ~ ^ _ * # 下划线/上划线的长度不得短于标题文本本身若文档只有一个顶级章节标题它会被提升为整个文档的子标题。这正是 RST 标题与 Markdown#前缀语法最直观的区别RST 用“装饰线”表达标题层级且不同层级应使用不同的装饰字符。三、行内标记L19–L26样本给出了 RST 四类行内标记的完整形态*emphasis* **strong emphasis** interpreted text inline literal http://docutils.sf.net/要点单星号*…*为强调emphasis双星号**…**为强强调strong emphasis单反引号interpreted text是解释型文本interpreted text可承载链接、角色等语义双反引号 inline literal 表示行内字面量内容不再参与任何标记解析——这也是为什么样本里连 - : ~ ^ _ * # 这样包含反引号与星号的字符串都能原样书写裸 URL如http://docutils.sf.net/会被识别为自动链接autolink在支持该扩展的渲染器中自动生成超链接。对 bat 的高亮器而言这段正是验证“反引号配对、星号配对、URL 识别”等 token 规则的最小用例集。四、四种列表L28–L864.1 无序列表- This is item 1 - This is item 2 - Bullets are -, * or . Continuing text must be aligned after the bullet and whitespace.L28–L40项目符号可用-、*、三种字符续行文本必须与“符号 空白”之后的起始位置对齐第一个条目之前与最后一个条目之后必须有空行条目之间的空行可选。4.2 有序列表3. This is the first item 4. This is the second item 5. Enumerators are arabic numbers, single letters, or roman numerals 6. List items should be sequentially numbered, but need not start at 1 #. This item is auto-enumeratedL42–L52枚举子可以是阿拉伯数字、单个字母或罗马数字条目须按顺序编号但不要求从 1 开始不过并非所有格式化器都尊重起始索引#.触发自动编号。4.3 定义列表what Definition lists associate a term with a definition.L54–L66术语term是单行短语定义是缩进的一至多个段落术语与定义之间不允许出现空行否则会被拆成两个普通段落。4.4 字段列表:Authors: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) :Version: 1.0 of 2001/08/08 :Dedication: To my father.L68–L76字段列表以:Field:开头常用于文档元数据作者、版本等字段名本身是结构化信息而非纯文本。4.5 选项列表-a command-line option a -b file options can have arguments and long descriptions --long options can be long also --inputfile long options can also have arguments /V DOS/VMS-style options tooL78–L86选项列表专为命令手册设计支持短选项、带参数的短选项、GNU 风格长选项--long、--inputfile以及 DOS/VMS 风格选项/V续行描述缩进对齐。对 bat 用户来说这段本身就是一个“高亮选项列表”的实际渲染样本。五、字面块与行块L88–L1645.1 字面块Literal Blocks:: Whitespace, newlines, blank lines, and all kinds of markup (like *this* or \this) is preserved by literal blocks.L88–L119核心规则一个只包含::的段落声明其后的缩进或引用文本为字面块空白、换行、空行与一切标记如*this*均按原样保留只含::的段落本身不会出现在结果中::也可以紧贴在任意段落末尾若前面是空白则省略不显示若前面是文字则转换为单个冒号如样本中like this::的写法字面块在文本回到“上一段落缩进级别”时结束因此允许逐行递减的锯齿形缩进样本 L117–L119 的We start here / and continue here / and end here.正是此用法对无缩进的字面块可以逐行加引用前缀样本注明其用途包括邮件引用与 Haskell 字面编程literate programming。5.2 行块Line Blocks文件的Line blocks小节L127–L164沿用了与字面块相同结构的示例文本。从源码结构看这一节的存在价值主要是让高亮器覆盖“行块声明”这一独立标记形态实际使用时行块用于逐行保留换行的场景如地址、诗歌。六、块引用与 Doctest 块L166–L181块引用block quote就是缩进段落且可以嵌套Block quotes are just: Indented paragraphs, and they may nest.Doctest 块是交互式 Python 会话片段以起始、以空行结束 print This is a doctest block. This is a doctest block.L174–L181高亮器需要区分“缩进段 块引用”与“缩进 Python 会话”这是 RST 高亮中较容易混淆的一对场景。七、两种表格L183–L211样本同时覆盖了 RST 的网格表grid table与简单表simple table----------------------------------- | Header 1 | Header 2 | Header 3 | | body row 1 | column 2 | column 3 | ----------------------------------- | body row 2 | Cells may span columns.| ----------------------------------- | body row 3 | Cells may | - Cells | ------------ span rows. | - contain | | body row 4 | | - blocks. | -----------------------------------要点L186–L198网格表用与|勾勒单元格边界分隔表头与表体单元格可以跨列Cells may span columns.、跨行Cells may span rows.甚至内嵌块级元素如无序列表简单表只依赖列分隔空格与边框 Inputs Output ------------ ------ A B A or B False False False True False True False True True True True True L200–L211这是一个真值表示例。表格是 RST 高亮中字符对齐最苛刻的部分任何一个的位置错位都会破坏单元格解析因此这段是测试样本中相当有分量的回归点。八、过渡符L213–L224------------过渡符transition是一条由至少 4 个重复标点字符构成的水平线用于表示内容切换。约束L222–L224过渡符不应出现在章节或文档的开头/结尾也不应两个过渡符紧邻。注意它与标题下划线在语法上相似但作用域完全不同——这正是高亮器需要区分的边界情况。九、脚注与引用L226–L2709.1 脚注样本给出了脚注的四种形态L226–L251数值脚注引用写作[5]_定义写作.. [5] A numerical footnote.注意]后面没有冒号自动编号脚注引用[#]_、定义.. [#] This is the first one.带标签的自动编号引用可命名如[#fourth]_与[#third]_定义写作.. [#third] a.k.a. third_自动符号脚注引用[*]_、定义.. [*] ...。脚注在最终排版中可能被重排例如统一移至“页面”底部。9.2 引用Citations.. [CIT2002] A citation (as often used in journals).引用标签允许包含字母数字、下划线、连字符与句点且不区分大小写。引用[this]_定义之后还可以在文中直接以标签名this_的方式指代它L267–L270。脚注与引用是 RST 文档中“引用语法”的两套并行机制前者用于文档内部注释后者用于学术式文献标注——两者的高亮规则下划线引用 ..定义块也在样本中得到完整覆盖。十、超链接目标与隐式引用L272–L295样本覆盖了 RST 链接目标hyperlink target的全部形态External hyperlinks, like Python_. .. _Python: http://www.python.org/ External hyperlinks, like Python http://www.python.org/_. Internal crossreferences, like example_. .. _example: This is an example crossreference target. Python_ is my favourite programming language__. __ Python_要点外部链接可定义为.. _Python: URL的形式文中以Python_引用也可以内联书写显式外部链接Python http://www.python.org/_内部交叉引用目标不带 URI.. _example:__开头的是匿名链接目标按出现顺序与...__形式的引用配对标题本身就是目标样本随后出现了一级标题Titles are targets, too文中可以直接用Titles are targets, too_做隐式引用L292–L295——这是隐式引用implicit reference的典型用法也是高亮器必须能区分“下划线结尾是目标引用”与“普通文本”的难点。十一、指令、替换引用与注释L297–L320For instance: .. image:: images/ball1.gif The |biohazard| symbol must be used on containers used to dispose of medical waste. .. |biohazard| image:: biohazard.png.. image::是指令directive.. 名称:: 参数结构用于嵌入图片等结构化内容|biohazard|是替换引用substitution reference配合.. |biohazard| image::定义可在全文档中复用同一图形.. This text will not be shown ...是注释comment以..开头的块不参与正文渲染不同输出格式处理方式不同如 HTML 可能输出为 HTML 注释空注释前后都有空行的单独一行..不会“吞掉”后续的块——样本最后特意展示了一段缩进文本在空注释之后仍然被正常保留L306–L320这是对解析器“注释边界”行为的重要回归点。十二、如何复现用 bat 查看这个样本在仓库中直接验证本文所有示例的高亮效果可运行测试脚本同款参数bat --no-config --styleplain --coloralways \ --themeMonokai Extended --italic-textalways \ tests/syntax-tests/source/reStructuredText/reference.rst注意事项与适用前提期望基线highlighted/reStructuredText/reference.rst是用Monokai Extended主题、plain样式生成的若改用默认主题或默认样式输出会包含不同的装饰行不能直接逐字节对比若某次高亮规则变更导致样本渲染变化标准流程是先运行 create_highlighted_versions.py 重新生成基线再由 compare_highlighted_versions.py 审查差异是否合理——这正是该参考文件作为“全量语法探针”的意义所在bat 依据扩展名选择 RST 语法的逻辑见 src/syntax_mapping.rs扩展名未命中时的首行回退检测见 src/assets.rs 的get_first_line_syntax小结reference.rst 这份 320 行的样本按“标题 → 行内 → 列表 → 块 → 表格 → 过渡 → 脚注/引用 → 链接 → 指令/注释”的顺序完整铺开了 reStructuredText 的语法版图。对 bat 而言它不只是一个被高亮的普通文档而是一套覆盖 RST 全部标记形态的高亮回归用例对 RST 使用者而言它也是一份可以直接对照复制的语法参考——两者共用同一份文件这正是把它放进 tests/syntax-tests/source/reStructuredText/ 的巧妙之处。【免费下载链接】batA cat(1) clone with wings.项目地址: https://gitcode.com/GitHub_Trending/ba/bat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
bat 中 reStructuredText 高亮测试样本实战以 reference.rst 全量参考文件为主线的 RST 语法详解【免费下载链接】batA cat(1) clone with wings.项目地址: https://gitcode.com/GitHub_Trending/ba/bat本文以 bat 仓库中的 tests/syntax-tests/source/reStructuredText/reference.rst 为主体逐节拆解这份 reStructuredText以下简称 RST全量语法参考文件覆盖的每一种标记元素——从标题、行内标记、四种列表、字面块、表格到脚注与指令并结合 bat 的语法高亮测试流水线create_highlighted_versions.py、compare_highlighted_versions.py说明这个样本文件如何为 bat 的 RST 高亮能力提供回归验证。读完后你既能把它当作一份可复制的 RST 语法手册也能理解 bat 是如何用“源文件 固定主题期望输出”的方式保证高亮结果稳定的。一、reference.rst 在 bat 测试体系中的位置bat 的高亮能力依赖其内置的语法定义集合序列化打包在 assets/syntaxes.bin 中。为验证每种语法的渲染结果稳定可复现仓库维护了一套“源样本 → 期望高亮输出”的测试资产源样本位于 tests/syntax-tests/source/每个子目录对应一种语法reStructuredText/目录下的reference.rst即本篇主体期望输出位于 tests/syntax-tests/highlighted/reStructuredText/reference.rst内容是用固定参数高亮后的带 ANSI 颜色序列的文本create_highlighted_versions.py 负责批量重新生成期望输出其固定参数为--no-config --styleplain --coloralways --themeMonokai Extended --italic-textalways脚本刻意避开“默认主题”因为默认主题可能随 macOS 外观设置变化改用--no-config与固定主题保证输出在任意环境下可比较。update.sh 与 compare_highlighted_versions.py 则分别承担“刷新基线”与“对比差异”的职责。选一份覆盖 RST 全部核心语法的参考文件作为样本非常合理只要这份文件中每类标记都得到稳定、正确的高亮RST 文件的其他典型内容也基本被覆盖。而 bat 为文件选择语式的逻辑扩展名匹配、first_line回退检测等可以在 src/syntax_mapping.rs 与 src/assets.rs 中查看高亮与输出渲染的关键路径位于 src/printer.rs。二、标题与文档结构L1–L17文件开头即示范了 RST 的标题体系 Title Subtitle --------对应规则见 reference.rst L5–L17标题由下划线或上下线构成使用的必须是可打印的非字母数字 7-bit ASCII 字符官方推荐使用的字符集是 - : ~ ^ _ * # 下划线/上划线的长度不得短于标题文本本身若文档只有一个顶级章节标题它会被提升为整个文档的子标题。这正是 RST 标题与 Markdown#前缀语法最直观的区别RST 用“装饰线”表达标题层级且不同层级应使用不同的装饰字符。三、行内标记L19–L26样本给出了 RST 四类行内标记的完整形态*emphasis* **strong emphasis** interpreted text inline literal http://docutils.sf.net/要点单星号*…*为强调emphasis双星号**…**为强强调strong emphasis单反引号interpreted text是解释型文本interpreted text可承载链接、角色等语义双反引号 inline literal 表示行内字面量内容不再参与任何标记解析——这也是为什么样本里连 - : ~ ^ _ * # 这样包含反引号与星号的字符串都能原样书写裸 URL如http://docutils.sf.net/会被识别为自动链接autolink在支持该扩展的渲染器中自动生成超链接。对 bat 的高亮器而言这段正是验证“反引号配对、星号配对、URL 识别”等 token 规则的最小用例集。四、四种列表L28–L864.1 无序列表- This is item 1 - This is item 2 - Bullets are -, * or . Continuing text must be aligned after the bullet and whitespace.L28–L40项目符号可用-、*、三种字符续行文本必须与“符号 空白”之后的起始位置对齐第一个条目之前与最后一个条目之后必须有空行条目之间的空行可选。4.2 有序列表3. This is the first item 4. This is the second item 5. Enumerators are arabic numbers, single letters, or roman numerals 6. List items should be sequentially numbered, but need not start at 1 #. This item is auto-enumeratedL42–L52枚举子可以是阿拉伯数字、单个字母或罗马数字条目须按顺序编号但不要求从 1 开始不过并非所有格式化器都尊重起始索引#.触发自动编号。4.3 定义列表what Definition lists associate a term with a definition.L54–L66术语term是单行短语定义是缩进的一至多个段落术语与定义之间不允许出现空行否则会被拆成两个普通段落。4.4 字段列表:Authors: Tony J. (Tibs) Ibbs, David Goodger (and sundry other good-natured folks) :Version: 1.0 of 2001/08/08 :Dedication: To my father.L68–L76字段列表以:Field:开头常用于文档元数据作者、版本等字段名本身是结构化信息而非纯文本。4.5 选项列表-a command-line option a -b file options can have arguments and long descriptions --long options can be long also --inputfile long options can also have arguments /V DOS/VMS-style options tooL78–L86选项列表专为命令手册设计支持短选项、带参数的短选项、GNU 风格长选项--long、--inputfile以及 DOS/VMS 风格选项/V续行描述缩进对齐。对 bat 用户来说这段本身就是一个“高亮选项列表”的实际渲染样本。五、字面块与行块L88–L1645.1 字面块Literal Blocks:: Whitespace, newlines, blank lines, and all kinds of markup (like *this* or \this) is preserved by literal blocks.L88–L119核心规则一个只包含::的段落声明其后的缩进或引用文本为字面块空白、换行、空行与一切标记如*this*均按原样保留只含::的段落本身不会出现在结果中::也可以紧贴在任意段落末尾若前面是空白则省略不显示若前面是文字则转换为单个冒号如样本中like this::的写法字面块在文本回到“上一段落缩进级别”时结束因此允许逐行递减的锯齿形缩进样本 L117–L119 的We start here / and continue here / and end here.正是此用法对无缩进的字面块可以逐行加引用前缀样本注明其用途包括邮件引用与 Haskell 字面编程literate programming。5.2 行块Line Blocks文件的Line blocks小节L127–L164沿用了与字面块相同结构的示例文本。从源码结构看这一节的存在价值主要是让高亮器覆盖“行块声明”这一独立标记形态实际使用时行块用于逐行保留换行的场景如地址、诗歌。六、块引用与 Doctest 块L166–L181块引用block quote就是缩进段落且可以嵌套Block quotes are just: Indented paragraphs, and they may nest.Doctest 块是交互式 Python 会话片段以起始、以空行结束 print This is a doctest block. This is a doctest block.L174–L181高亮器需要区分“缩进段 块引用”与“缩进 Python 会话”这是 RST 高亮中较容易混淆的一对场景。七、两种表格L183–L211样本同时覆盖了 RST 的网格表grid table与简单表simple table----------------------------------- | Header 1 | Header 2 | Header 3 | | body row 1 | column 2 | column 3 | ----------------------------------- | body row 2 | Cells may span columns.| ----------------------------------- | body row 3 | Cells may | - Cells | ------------ span rows. | - contain | | body row 4 | | - blocks. | -----------------------------------要点L186–L198网格表用与|勾勒单元格边界分隔表头与表体单元格可以跨列Cells may span columns.、跨行Cells may span rows.甚至内嵌块级元素如无序列表简单表只依赖列分隔空格与边框 Inputs Output ------------ ------ A B A or B False False False True False True False True True True True True L200–L211这是一个真值表示例。表格是 RST 高亮中字符对齐最苛刻的部分任何一个的位置错位都会破坏单元格解析因此这段是测试样本中相当有分量的回归点。八、过渡符L213–L224------------过渡符transition是一条由至少 4 个重复标点字符构成的水平线用于表示内容切换。约束L222–L224过渡符不应出现在章节或文档的开头/结尾也不应两个过渡符紧邻。注意它与标题下划线在语法上相似但作用域完全不同——这正是高亮器需要区分的边界情况。九、脚注与引用L226–L2709.1 脚注样本给出了脚注的四种形态L226–L251数值脚注引用写作[5]_定义写作.. [5] A numerical footnote.注意]后面没有冒号自动编号脚注引用[#]_、定义.. [#] This is the first one.带标签的自动编号引用可命名如[#fourth]_与[#third]_定义写作.. [#third] a.k.a. third_自动符号脚注引用[*]_、定义.. [*] ...。脚注在最终排版中可能被重排例如统一移至“页面”底部。9.2 引用Citations.. [CIT2002] A citation (as often used in journals).引用标签允许包含字母数字、下划线、连字符与句点且不区分大小写。引用[this]_定义之后还可以在文中直接以标签名this_的方式指代它L267–L270。脚注与引用是 RST 文档中“引用语法”的两套并行机制前者用于文档内部注释后者用于学术式文献标注——两者的高亮规则下划线引用 ..定义块也在样本中得到完整覆盖。十、超链接目标与隐式引用L272–L295样本覆盖了 RST 链接目标hyperlink target的全部形态External hyperlinks, like Python_. .. _Python: http://www.python.org/ External hyperlinks, like Python http://www.python.org/_. Internal crossreferences, like example_. .. _example: This is an example crossreference target. Python_ is my favourite programming language__. __ Python_要点外部链接可定义为.. _Python: URL的形式文中以Python_引用也可以内联书写显式外部链接Python http://www.python.org/_内部交叉引用目标不带 URI.. _example:__开头的是匿名链接目标按出现顺序与...__形式的引用配对标题本身就是目标样本随后出现了一级标题Titles are targets, too文中可以直接用Titles are targets, too_做隐式引用L292–L295——这是隐式引用implicit reference的典型用法也是高亮器必须能区分“下划线结尾是目标引用”与“普通文本”的难点。十一、指令、替换引用与注释L297–L320For instance: .. image:: images/ball1.gif The |biohazard| symbol must be used on containers used to dispose of medical waste. .. |biohazard| image:: biohazard.png.. image::是指令directive.. 名称:: 参数结构用于嵌入图片等结构化内容|biohazard|是替换引用substitution reference配合.. |biohazard| image::定义可在全文档中复用同一图形.. This text will not be shown ...是注释comment以..开头的块不参与正文渲染不同输出格式处理方式不同如 HTML 可能输出为 HTML 注释空注释前后都有空行的单独一行..不会“吞掉”后续的块——样本最后特意展示了一段缩进文本在空注释之后仍然被正常保留L306–L320这是对解析器“注释边界”行为的重要回归点。十二、如何复现用 bat 查看这个样本在仓库中直接验证本文所有示例的高亮效果可运行测试脚本同款参数bat --no-config --styleplain --coloralways \ --themeMonokai Extended --italic-textalways \ tests/syntax-tests/source/reStructuredText/reference.rst注意事项与适用前提期望基线highlighted/reStructuredText/reference.rst是用Monokai Extended主题、plain样式生成的若改用默认主题或默认样式输出会包含不同的装饰行不能直接逐字节对比若某次高亮规则变更导致样本渲染变化标准流程是先运行 create_highlighted_versions.py 重新生成基线再由 compare_highlighted_versions.py 审查差异是否合理——这正是该参考文件作为“全量语法探针”的意义所在bat 依据扩展名选择 RST 语法的逻辑见 src/syntax_mapping.rs扩展名未命中时的首行回退检测见 src/assets.rs 的get_first_line_syntax小结reference.rst 这份 320 行的样本按“标题 → 行内 → 列表 → 块 → 表格 → 过渡 → 脚注/引用 → 链接 → 指令/注释”的顺序完整铺开了 reStructuredText 的语法版图。对 bat 而言它不只是一个被高亮的普通文档而是一套覆盖 RST 全部标记形态的高亮回归用例对 RST 使用者而言它也是一份可以直接对照复制的语法参考——两者共用同一份文件这正是把它放进 tests/syntax-tests/source/reStructuredText/ 的巧妙之处。【免费下载链接】batA cat(1) clone with wings.项目地址: https://gitcode.com/GitHub_Trending/ba/bat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
