Renders AGS Script and Public key asc files as AsciiDoc

[edmundito]

Originally described in github-linguist/linguist#1638:

The markup renderer currently detects all files with .asc extensions as AsciiDoc, although the file extension is also used for AGS Script and Public Key files.

markup/lib/github/markups.rb

Line 29 in 589f299

markup(:asciidoctor, /adoc|asc(iidoc)?/) do |content|

This leads to files to be rendered in an unreadable way:
https://github.com/vasofilipov/wisp-game/blob/master/Code/ASCII%20Quick%20Converter.asc

[mojavelinux]

I'm a strong supporter of dropping .asc as a recognized AsciiDoc file extension for this very reason. I believe that .adoc and .asciidoc are sufficient and have helped to move the industry in that direction. As the lead of the Asciidoctor project and AsciiDoc language maintainer, you have my vote.

[bkeepers]

I'm a strong supporter of dropping .asc as a recognized AsciiDoc file extension for this very reason.

Sounds good to me.

/cc @github/languages @github/user-content

[aroben]

Any idea how common .asc vs .adoc/.asciidoc is on GitHub?

[edmundito]

Unsure, but https://github.com/progit/progit2, one of the most definitive guides to using git, uses .asc files.

[mojavelinux]

The extension is prominent mostly in the O'Reilly author community because, for a long time (maybe even still), they advocated for the use of .asc. However, I've recommended to O'Reilly for them to switch their default extension in Atlas to .adoc.

[bkeepers]

I talked with @arfon and @schacon about this. I think we will need to push the detection into https://github.com/github/linguist, and only render it if linguist thinks it's asciidoc.

We're also going to have to improve our asciidoc heuristic.

[schacon]

Sorry about that - both Pro Git and the Atom guide are .asc formatted. It wouldn't be horrible to change them though, if it was really important. I just never knew it was an issue.

[justinclift]

@mojavelinux This is just a file extension change needed yeah? There's no change in actual markup needed (eg for Pro Git 2)?

If that's the case, it should be reasonably straightforward to adjust Pro Git 2 at least. 😄

[mojavelinux]

Sorry about that - both Pro Git and the Atom guide are .asc formatted ... I just never knew it was an issue.

No need to apologize. This is a fairly new recommendation and probably just getting the light of day here.

The previous AsciiDoc leadership was never clear about file extensions. In fact, the original guide recommended the use of .txt for the longest time (it may even still say that). As a result, we ended up with a plethora of extensions as the community made them up (including O'Reilly).

The new leadership (under Asciidoctor) is helping to provide some guidance and cleanup ambiguities in AsciiDoc. We recognized the file extension conflict with the armored file format and added the recommendation against using it on asciidoctor.org. If we get it dropped from GitHub, then it will solidify this recommendation (and resolve the conflict).

In short, it's not a huge deal, but fixing these little broken windows makes AsciiDoc stronger.

[mojavelinux]

I think we will need to push the detection into https://github.com/github/linguist, and only render it if linguist thinks it's asciidoc.

That's actually a nice approach. I still like the idea of steering writers away from the .asc extension, but this way we could do that through communication instead of by breaking existing behavior.

[kivikakk]

We're now using Linguist (thanks to #537), and its heuristics do a good job of picking the correct actual language given a .asc file 👍