【问题标题】:How do the cross references in spec.txt for GFM work?GFM 的 spec.txt 中的交叉引用如何工作?
【发布时间】:2019-11-06 23:40:17
【问题描述】:

前奏

GFM spec中是这样说的:

本文档是从文本文件 spec.txt 生成的,该文件是用 Markdown 编写的,带有一个用于并行测试的小扩展名。脚本tools/makespec.py 可用于将spec.txt 转换为HTML 或CommonMark(然后可以转换为其他格式)。

我无法找到包含这些文件的公共存储库,但可以在同一网站下找到 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 中,链接[characters] 以及链接[character](@) 已转换为此交叉引用链接:

https://github.github.com/gfm/#character

此语法是否在 GFM 中实现交叉引用(又名锚点)?有一个 popular question about such a feature 表明不存在交叉引用的纯 Markdown 解决方案 - 但是,如果在解析 spec.txt 的解析器中实现了这种基于 (@) 的语法,为什么规范中没有指定它?

【问题讨论】:

  • Github 在 github/cmark-gfm 托管了 Commonmark 扩展版本的代码。有趣的是,该回购的Issue #93 引起了人们的担忧,即github.github.com/gfm 的内容没有公开回购。但是,github/cmark-gfm 存储库中有 spec.txt 的副本。
  • 我刚刚检查过,commonmark/cmark 的非扩展 Commonmark 实现也包含与spec.txt 相同的语法。因此,这不是 GFM 特有的,而是通用的通用标记。

标签: markdown github-flavored-markdown


【解决方案1】:

Commonmark 规范的官方 repo 可以在commonmark/commonmark-spec 找到(其他 repos 中的规范副本从这里复制)。我们可以看到该仓库中的文件spec.txt 也具有相同的语法contains。因此,这不是 GFM 特有的,而是通用的 Commonmark(GFM 是其扩展)。

正如commonmark/commonmark-spec#578(可能还有其他地方)中关于spec.txt 文件的解释:

注意:这不是一个独立的通用标记文件。它在一个特殊的 设计为使用tools/make_spec.lua 处理的格式。

事实上,如果我们查看 repo 中的 tools/make_spec.lua,我们会发现它是一个包装脚本,它在以多种支持的格式之一输出规范之前预处理 spec.txt 文件。请注意,其中一种输出格式是 Commonmark。如果您以commonmark 作为输出格式运行脚本,您将获得一个带有常规Commonmark 链接的Commonmark 文档,而不是特殊语法。事实上,如果您将 spec.txt 文件直接提供给 Commonmark(没有在 tools/make_spec.lua 中进行预处理),您将不会得到一个包含正确格式链接的文档作为回报。因此,我们可以得出结论,所讨论的语法不是 Commonmark,而是一些仅用于编写规范的自定义附加组件。这可以解释为什么它没有在规范中指定。

不幸的是,我无法在任何地方找到有关语法如何工作的任何文档。规范的Readme 简要提到了规范中使用的特殊代码块语法,但没有涉及内部链接。

【讨论】:

  • 感谢您追查此事。这很有意义,尽管我曾寄希望于交叉引用可能有一个秘密的 GFM/CommonMark 规范 ;-)。
猜你喜欢
  • 2021-04-07
  • 1970-01-01
  • 1970-01-01
  • 1970-01-01
  • 2021-01-21
  • 1970-01-01
  • 2014-09-07
  • 1970-01-01
  • 1970-01-01
相关资源
最近更新 更多