0

Prelude

In the GFM spec, it is said that:

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).

I was unable to find a public repository containing these files, but spec.txt can be found under the same web directory as the spec itself. This is not my main question, but I would be happy if someone could point out a repository where these files are officially maintained.

Main Assumption

According to the above quote, I assume that all code in spec.txt, aside from the code dedicated to side-by-side tests, is legitimate GFM.

Main Question

In spec.txt, there is the following code:

## 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.

In the rendered spec, the link [characters] and also the link [character](@) have been converted to this cross reference link:

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

Does this syntax implement cross references (aka named anchors) in GFM? There is a popular question about such a feature which suggests that no pure Markdown solution for cross references exists - however, if this (@)-based syntax is implemented in the parser that parsed spec.txt, why is it not specified in the spec?

Jesko Hüttenhain
  • 1,278
  • 10
  • 28
  • Github hosts the code for their extended version of Commonmark at [github/cmark-gfm](https://github.com/github/cmark-gfm/). Interestingly, [Issue #93](https://github.com/github/cmark-gfm/issues/93) of that repo raises the concern that there is not a public repo for the content of https://github.github.com/gfm/. However, there is a copy of [spec.txt](https://github.com/github/cmark-gfm/blob/master/test/spec.txt) in the `github/cmark-gfm` repo. – Waylan Nov 05 '19 at 19:24
  • I just checked and the non-extended Commonmark implementation at [commonmark/cmark](https://github.com/commonmark/cmark) also contains the same syntax in [spec.txt](https://github.com/commonmark/cmark/blob/master/test/spec.txt#L282). Therefore, this is not specific to GFM, but to Commonmark in general. – Waylan Nov 05 '19 at 19:54

1 Answers1

1

The official repo for the Commonmark spec can be found at 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 the same syntax. Therefore, this is not specific to GFM, but to Commonmark in general (of which GFM is an extension).

As explained in commonmark/commonmark-spec#578 (and possibly other places) regarding the spec.txt file:

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.

In fact, if we look at tools/make_spec.lua in the repo, we see that it is a wrapper script which preprocesses the spec.txt file before outputing the spec in one of multiple supported formats. Note that one of those output formats is Commonmark. If you run the script with commonmark as the output format, you will get a Commonmark document with regular Commonmark links in place of the special syntax. In fact, if you feed the spec.txt file directly to Commonmark (without the preprocessing in tools/make_spec.lua) you will not get a document with correctly formatted links in return. Therefore, we can conclude that the syntax in question is not Commonmark, but some custom add-on which is only used for authoring the spec. That would explain why it is not specified in the spec.

Unfortunately, I am unable to find any documentation of how the syntax works anywhere. The Readme for the spec briefly mentions the special codeblock syntax used in the spec, but does not touch on internal links.

Waylan
  • 37,164
  • 12
  • 83
  • 109
  • Thanks for chasing this down. That makes a lot of sense, although I had brought my hopes up there might be a secret GFM/CommonMark spec for cross references ;-). – Jesko Hüttenhain Nov 07 '19 at 19:43