Incompatibility with rST spec: code vs include

[flyx]

rST's include directive provides a parameter code for including files that should be parsed as source code which may be highlighted. This is missing in Nim. However, Nim provides a non-standard, undocumented (at least not here) file parameter for code (and the nonstandard code-block directive).

It would be better to implement the specification for include instead of making undocumented extensions elsewhere.

[Araq]

These extensions have been copied from Sphinx or similar before rST got official support for this feature.

[timotheecour]

I wonder if this kind of non-standard extensions cause some rst files to be incorrectly parsed by github's linguist eg:

• https://github.com/nim-lang/Nim/blob/devel/doc/manual.rst displays without any markup (alas one of the most important files in docs)
  it's being detected as rst though: https://github.com/nim-lang/Nim/search?q=filename%3Amanual.rst&unscoped_q=filename%3Amanual.rst&type=Code
  shows detected lang=reStructuredText
  so my 1st though (using a .gitattributes file to override the language as prescribed in https://github.com/github/linguist) would not help
• other rst files seem to render fine

[timotheecour]

I wonder if this kind of non-standard extensions cause some rst files to be incorrectly parsed by github's linguist eg:

I've fixed this in #17092, it now renders fine in github, and was unrelated to use of non-standard extensions.

[Araq]

We moved to Markdown.