Fix typos in troubleshooting.md #6365
Conversation
Fix typos + Add reference to go-enry's divergences from Linguist.
docs/troubleshooting.md
Outdated
| @@ -70,4 +70,4 @@ Grammars will only be updated in patch releases if the patch release is specific | |||
|
|
|||
| Note: New languages will not appear in GitHub's search results for some time after the pull request has been merged and the new Linguist release deployed to GitHub.com. | |||
| This is because GitHub's search uses [go-enry](https://github.com/go-enry/go-enry) for language detection which tends to lag behind Linguist by a few weeks to months. | |||
| This in turn requires an update to the underlying search code once go-enry is inline with Linguist. | |||
| This in turn requires an update to the underlying search code once go-enry is inline with Linguist (See also go-enry's list of [divergences from Linguist](https://github.com/go-enry/go-enry#divergences-from-linguist)). | |||
There was a problem hiding this comment.
I'm not sure this is relevant enough to Linguist to warrant inundating readers with the gory details of portability differences between various regular expression engines. Keep in mind, most users perusing this document are probably in a rush, so they're more likely to expect missing details to be included in pages linked to from a troubleshooting answer.
There was a problem hiding this comment.
Maybe there is too many elements in that list that won't be relevant to most people, but I think there should be at least a mention that go-enry doesn't support linguist-language overrides in the .gitattrubutes.
Overriding languages and types though .gitattributes is not yet supported. See src-d/enry#18.
I know that I was confused about this multiple times until I discovered that in the list of divergences.
It's especially weird when you click on a language featured in the language stats bar and code search tells you there is no files with that language in the project :/
For example, if you go to the Fortran stdlib repo, the language breakdown tells you it's mostly Fortran, but when you click on it, code search tells you that no Fortran files are found.
And all that is because all the Fortran code uses the .fypp extension override in .gitattributes :
*.fypp linguist-language=fortran
Perhaps, this is just a case where the extension should be properly added to Linguist, but there is a lot of cases where the override in the .gitattributes file is the only option and this can lead to some confusion.
There was a problem hiding this comment.
It's especially weird when you click on a language featured in the language stats bar and code search tells you there is no files with that language in the project :/
Wait, so that's the culprit behind all those flaky, confusing code-listings seen when clicking certain languages in project stat-bars? 😕 Finally, I now know where years of “missing” INI files went in my dotfiles repository…
but I think there should be at least a mention that go-enry doesn't support
linguist-languageoverrides in the.gitattributes
This would be more suited to a separate troubleshooting entry explaining why some files aren't being listed when filtering by language (ideally after the “My repository is detected as the wrong language” entry). Such an addition warrants its own PR, however.
In the mean time, we should avoid repeating ourselves; this troubleshooting entry already includes a link to the go-enry repository; users can find their own way to the “Divergences from Linguist” section if they so choose to.
Fix typos
+ Add reference to go-enry's divergences from Linguist.