Suggestion: Move all grammar-related metadata to `grammars.yml`

Author: AlhadisCreated Sep 2, 2020Updated Jul 21, 2026

Currently, metadata pertaining to grammars and case-by-case exceptions are handled in four different places:

.gitmodules specifies URLs.
grammars.yml specifies scopes.
tools/grammars/compiler/data.go specifies scope-maps and case-by-case overrides
vendor/licenses/config.yml identifies (for Licensee) which grammars had their licenses manually-reviewed

Moreover, the difficulties related by @pastra98 made me realise there's more we could be doing with regards to locating grammar and license files. Specifically, we should be able to provide a manual path if need be — the currently hardcoded search locations can remain the default for grammars without a src: field defined, or whatever.

Here's how it *might* look.

yaml

# Each entry correlates to a directory in "vendor/grammars/#{key}"
--
abl-tmlanguage:
    license: MIT
    source: chriscamicas/abl-tmlanguage
    scopes:
        - source-abl
    
    # Location of files inside submodule repository. Usually
    # calculated automatically, though maybe it makes sense
    # to always provide this list, as opposed to only those
    # grammars with non-standard file locations?
    files:
        grammar: abl.tmLanguage.json
        license: LICENSE

actionscript3-tmbundle:
    license: MIT
    source: simongregory/actionscript3-tmbundle
    scopes:
        - source.actionscript.3
        - text.html.asdoc
        - text.xml.flex-config

c.tmbundle:
    license: MIT
    source: textmate/c.tmbundle
    scopes:
        - source.c
        - source.c++
        - source.c.platform
    aliases:
        source.c++: source.cpp

hy.tmLanguage:
    license: MIT
    source: Slowki/hy.tmLanguage
    scopes:
        - source.hy
    paths:
        - hy.json
        - LICENSE.md

language-roff:
    license: ISC
    source: Alhadis/language-roff
    scopes:
        - hidden.manref
        - source.ditroff
        - source.ditroff.desc
        - source.gremlin
        - source.ideal
        - source.pic
        - text.roff
        - text.runoff

sublimesystemverilog:
    license: MIT
    source: https://bitbucket.org/Clams/sublimesystemverilog/get/default.tar.gz
    scopes:
        - source.systemverilog
        - source.ucfconstraints

Genshi.tmbundle:
    license: MIT
    source: https://svn.edgewall.org/repos/genshi/contrib/textmate/Genshi.tmbundle/Syntaxes/Markup%20Template%20%28XML%29.tmLanguage
    scopes:
        - text.xml.genshi

Thoughts?

EDIT: Oh yeah, it'd also be nice if we refined our terminology a little, because it's confusing to refer to both a TextMate compatible grammar file and the submodule containing it as a "grammar" (maybe "grammar-source" for the latter?) Given most of the grammars I write nowadays are almost exclusively added to language-etc (a super-bundle of whatever I can't be fucked publishing separately anymore, but nothing specific), it'd be a helpful distinction.

Source: github-linguist/linguist

View original on GitHub View discussion on GitHub