spec.txt 中 GFM 的交叉引用如何工作?
How do the cross references in spec.txt for GFM work?
序曲
在GFM spec中表示:
This document is generated from a text file, spec.txt
, written in Markdown with a small extension for the side-by-side tests. The script tools/makespec.py
can be used to convert spec.txt
into HTML or CommonMark (which can then be converted into other formats).
我无法找到包含这些文件的 public 存储库,但 spec.txt
可以在同一网站下找到
目录作为规范本身。这不是我的主要问题,但如果有人能指出正式维护这些文件的存储库,我会很高兴。
主要假设
根据上面的引述,我假设 spec.txt
中的所有代码,除了专门用于并排测试的代码外,都是 合法的 GFM。
主要问题
在spec.txt
中有如下代码:
## Characters and lines
Any sequence of [characters] is a valid CommonMark
document.
A [character](@) is a Unicode code point. Although some
code points (for example, combining accents) do not correspond to
characters in an intuitive sense, all code points count as characters
for purposes of this spec.
在 rendered spec 中,link [characters]
以及 link [character](@)
已转换为此交叉引用 link:
https://github.github.com/gfm/#character
此语法是否在 GFM 中实现交叉引用(也称为命名锚点)?有一个 popular question about such a feature 表明不存在用于交叉引用的纯 Markdown 解决方案 - 但是,如果在解析 spec.txt
的解析器中实现了这种基于 (@)
的语法,为什么没有指定在规范中?
可以在 commonmark/commonmark-spec (copies of the spec in other repos are copied from here). We can see that the file spec.txt
in that repo also contains 相同的语法中找到 Commonmark 规范的官方仓库。因此,这不是特定于 GFM,而是通用的 Commonmark(GFM 是其扩展)。
如 commonmark/commonmark-spec#578(可能还有其他地方)关于 spec.txt
文件的解释:
Note: this is NOT a standalone commonmark file. It is in a special
format which is designed to be processed using tools/make_spec.lua
.
事实上,如果我们查看 repo 中的 tools/make_spec.lua,我们会发现它是一个包装脚本,它在以多种支持格式之一输出规范之前预处理 spec.txt
文件。请注意,其中一种输出格式是 Commonmark。如果您 运行 以 commonmark
作为输出格式的脚本,您将获得一个 Commonmark 文档,其中包含常规 Commonmark 链接而不是特殊语法。事实上,如果您将 spec.txt
文件直接提供给 Commonmark(没有 tools/make_spec.lua
中的预处理),您将 而不是 获得 [=] 中具有正确格式链接的文档32=]。因此,我们可以得出结论,有问题的语法不是 Commonmark,而是一些仅用于编写规范的自定义附加组件。这可以解释为什么它没有在规范中指定。
不幸的是,我无法在任何地方找到有关该语法如何工作的任何文档。规范的 Readme 简要提及规范中使用的特殊代码块语法,但未涉及内部链接。
序曲
在GFM spec中表示:
This document is generated from a text file,
spec.txt
, written in Markdown with a small extension for the side-by-side tests. The scripttools/makespec.py
can be used to convertspec.txt
into HTML or CommonMark (which can then be converted into other formats).
我无法找到包含这些文件的 public 存储库,但 spec.txt
可以在同一网站下找到
目录作为规范本身。这不是我的主要问题,但如果有人能指出正式维护这些文件的存储库,我会很高兴。
主要假设
根据上面的引述,我假设 spec.txt
中的所有代码,除了专门用于并排测试的代码外,都是 合法的 GFM。
主要问题
在spec.txt
中有如下代码:
## Characters and lines
Any sequence of [characters] is a valid CommonMark
document.
A [character](@) is a Unicode code point. Although some
code points (for example, combining accents) do not correspond to
characters in an intuitive sense, all code points count as characters
for purposes of this spec.
在 rendered spec 中,link [characters]
以及 link [character](@)
已转换为此交叉引用 link:
https://github.github.com/gfm/#character
此语法是否在 GFM 中实现交叉引用(也称为命名锚点)?有一个 popular question about such a feature 表明不存在用于交叉引用的纯 Markdown 解决方案 - 但是,如果在解析 spec.txt
的解析器中实现了这种基于 (@)
的语法,为什么没有指定在规范中?
可以在 commonmark/commonmark-spec (copies of the spec in other repos are copied from here). We can see that the file spec.txt
in that repo also contains 相同的语法中找到 Commonmark 规范的官方仓库。因此,这不是特定于 GFM,而是通用的 Commonmark(GFM 是其扩展)。
如 commonmark/commonmark-spec#578(可能还有其他地方)关于 spec.txt
文件的解释:
Note: this is NOT a standalone commonmark file. It is in a special format which is designed to be processed using
tools/make_spec.lua
.
事实上,如果我们查看 repo 中的 tools/make_spec.lua,我们会发现它是一个包装脚本,它在以多种支持格式之一输出规范之前预处理 spec.txt
文件。请注意,其中一种输出格式是 Commonmark。如果您 运行 以 commonmark
作为输出格式的脚本,您将获得一个 Commonmark 文档,其中包含常规 Commonmark 链接而不是特殊语法。事实上,如果您将 spec.txt
文件直接提供给 Commonmark(没有 tools/make_spec.lua
中的预处理),您将 而不是 获得 [=] 中具有正确格式链接的文档32=]。因此,我们可以得出结论,有问题的语法不是 Commonmark,而是一些仅用于编写规范的自定义附加组件。这可以解释为什么它没有在规范中指定。
不幸的是,我无法在任何地方找到有关该语法如何工作的任何文档。规范的 Readme 简要提及规范中使用的特殊代码块语法,但未涉及内部链接。