Confusing Documentation

[rgant]

It seems that 4 years ago this package recommended disabling the built in matching:

Sublime's bracket highlighter can clash with BH's and it advisable to disable Sublime's bracket matching visualization.

https://github.com/facelessuser/BracketHighlighter/blob/1ce9b7aac2bfde2c56504936fb46717ba01adca7/docs/src/markdown/usage.md?plain=1#L11C1-L11C120

Two years later this note was added:

/// note | Outdated Recommendation Previously, it was recommended to disable the following features, but this also disabled bracket related features in "expand selections" and such. This is no longer recommended.

https://github.com/facelessuser/BracketHighlighter/commit/2d61c1842f82a2baaefb192f125181d163b845c7

But the original recommendation in the first paragraph and in the quickstart.md remains.

So what are the currently recommended configuration changes to make in Sublime after installing BracketHighlighter? If I have clarity on what is recommended I am happy to open a PR to update the documentation.

[facelessuser]

@rgant It does seem the change in documentation wasn't thorough enough, and probably made a bit hurriedly.

Originally, it was suggested to disable all of ST's bracket matching via:

    "match_brackets": false,
    "match_brackets_angle": false,
    "match_brackets_braces": false,
    "match_brackets_content": false,
    "match_brackets_square": false,
    "match_tags": false

It was noted that this breaks Sublime's built-in expand command, and possibly other things. It was found that overriding your color scheme to just not highlight things is an option, so it was updated to suggest this.

{
    "variables": {},
    "globals":
    {
        "bracket_contents_options": "none",
        "brackets_options": "none",
        "tags_options": "none"
    },
    "rules": []
}

With that said, I just revised this since you posted this issue, and I found the following to work without breaking expansion. As a matter of fact, this has been by default for a long time, and I didn't realize I was using it.

    "match_brackets": false,
    "match_tags": false

It seems the above options control the visualization, while the other options disable the matching altogether.

So it would seem I need to clean up the documentation in this regard. If you find that my findings are not correct, feel free offer insight on what you found, otherwise it seems just disabling to two noted options is sufficient, but you could do a theme override if you run into issues.

[rgant]

I have been using "match_brackets": false for 7 years and never noticed an issue with code folding (which is what I think you mean by expansion?) I'm starting over with my Sublime Text setup today and trying to see what 7 year old things I no longer need. I currently have match_brackets and the rest on their true (except for angle brackets) default and am perfectly happy with the situation. The only config I felt necessary was to change the ctrl+m keybinding to use this package instead.

[facelessuser]

I don't mean code folding, I mean expand selection command. If you disable all the matching bracket options, when you expand selections using Sublime's default command, it expand past brackets. Using the smaller subset of options (just two) will expand to the brackets on each iteration, expanding out further. If it doesn't affect you because you don't use that command, then it doesn't really matter, but if you run into the issue, this is why.