branch: externals/indent-bars commit 95f583c2d55e01d01f21d67e689845d3beacdfb2 Author: JD Smith <93749+jdtsm...@users.noreply.github.com> Commit: GitHub <nore...@github.com>
Update README.md --- README.md | 37 +++++++++++++++++-------------------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index f418340ac6..704c53c838 100644 --- a/README.md +++ b/README.md @@ -191,18 +191,16 @@ For more information, check [the details](#tree-sitter-details). - `indent-bars-treesit-ignore-blank-lines-types`: A list of tree-sitter node types (as strings) inside of which to inhibit styling blank lines, like "module". - `indent-bars-ts-styling-scope`: Determine whether the `*-ts-*` variables apply to in-scope or (by default) out-of-scope styling. This is important because one of these styles is shared with the bar style in non-TS buffers. This allows the default style in non-TS buffers to match either the in-scope (default) or out-of-scope styling. -### Tree-sitter alternate styling variables +### Tree-sitter alternate in-scope/out-of-scope styling variables -By default, if tree-sitter and _scope focus_ are active (`indent-bars-treesit-scope`), the style and highlight settings above apply only to the _in-scope_ bars[^2]. You can separately configure an alternate style for the appearance of the _out-of-scope_ bars — i.e. the bars outside the current tree-sitter scope[^2]. Usually you'd want to de-emphasize out-of-scope bars somehow, but that's not required (go crazy). - -[^2]: Or visa versa if `indent-bars-ts-styling-scope` is set to `in-scope`. +By default, if tree-sitter and _scope focus_ are active (`indent-bars-treesit-scope`), the style and highlight settings above apply only to the _in-scope_ bars (or visa versa if `indent-bars-ts-styling-scope` is set to `in-scope`). You can separately configure an alternate style for the appearance of the _out-of-scope_ bars — i.e. the bars outside the current tree-sitter scope. Usually you'd want to de-emphasize out-of-scope bars somehow, but that's not required (go crazy). To customize the alternate bar appearance, you use the parallel set of custom variables with an `indent-bars-ts-` prefix. Each of these variables can be set similarly to their default counterparts to _fully_ configure alternate bar appearance, including color, depth highlighting, bar pattern, etc. -You can interchange the role of in-scope and out-of-scope using `indent-bars-ts-styling-scope`. This is useful if you prefer to have the _default_ style (e.g. the bar style in non-tree-sitter-enabled buffers) match the out-of-scope style within tree-sitter buffers (i.e. if you want to _emphasize_ scope, not _de-emphasize_ out-of-scope). +You can interchange the role of in-scope and out-of-scope using `indent-bars-ts-styling-scope`. This is useful if you prefer to have the _default_ style (e.g. the bar style in non-tree-sitter-enabled buffers) match the out-of-scope style within tree-sitter buffers (i.e. if you want to _emphasize_ bars within scope, not _de-emphasize_ out-of-scope bars). > [!NOTE] -> _Scope focus_ highlighting is completely independent of _current depth highlighting_, and you can style them separately, and can enable one or the other, both, or neither. +> _Scope focus_ highlighting is completely independent of _current depth highlighting_, and you can style them separately, and can enable one or the other, both, or neither. The `ts` custom variables for configuring the alternate styling are: @@ -217,8 +215,8 @@ The `ts` custom variables for configuring the alternate styling are: Each of these parallel variables has the same form as their equivalent non-`ts` version (the "parent" variable), with two additions: -1. Some (marked with [I] above) can optionally use _inheritance_ from their parent. Inheritance means any missing `:key` based elements are _inherited_ from the in-scope (parent) style. To configure whether this inheritance occurs, you can optionally set these variable values to a cons cell of the form `([no-]inherit . value)`, where `value` has the normal format for the parent variable. `inherit` (the default, if the cons cell is omitted and `value` is simply used as-is) means that a [...] -2. For any non-`:key` type values, the specific symbol value `'unspecified` can be set to indicate to use the parent's value for that slot. +1. Some (marked with [I] above) can optionally use _inheritance_ from their parent. Inheritance means any missing `:key`-based elements are _inherited_ from the parent style. To configure whether inheritance happens, you can optionally set these `[I]` variables to a cons cell of the form `([no-]inherit . value)`, where `value` has the normal format for the parent variable. `inherit` (the default, if the cons cell is omitted and `value` is simply used as-is) means that any unspecified [...] +2. For any non-`:key` type values, the specific symbol value `'unspecified` can be set to indicate using the parent's value for that slot. For example, a setting of: @@ -226,7 +224,7 @@ For example, a setting of: (setopt indent-bars-ts-color '(inherit unspecified :blend 0.15)) ``` -means to configure the color of alternate style bars as follows: +means to configure the color of the alternate style bars as follows: 1. use the color from the parent variable `indent-bars-color` (since it is `unspecified` here) 2. set `:blend` to 0.15 @@ -241,13 +239,12 @@ Sometimes different `indent-bars` settings are appropriate for different major m ```elisp (add-hook 'emacs-lisp-mode-hook (lambda () - (setq-local - indent-tabs-mode t ; make sure tabs-based indenting is on, even if we disable it globally + (setq-local indent-tabs-mode t ; make sure tabs-based indenting is on, even if we disable it globally indent-bars-no-descend-lists nil) ; elisp is mostly continued lists! allow bars to descend inside (indent-bars-mode 1))) ``` -Note that tree-sitter scope and wrap config are keyed to the parser _language_, which may be sufficient for tailoring these. +Note that tree-sitter scope and wrap config are keyed to the parser _language_, which may be sufficient for tailoring these (i.e. no buffer-local values needed). # Details and Caveats @@ -255,25 +252,25 @@ Note that tree-sitter scope and wrap config are keyed to the parser _language_, `indent-bars` works with either space- or tab-based indentation (see `indent-tabs-mode`). If possible, prefer space indentation, as it is faster. -Note that some modes explicitly enable or disable `indent-tabs-mode`. If the value of that variable does not match the actual indentation used in a file (e.g. file is indented with tabs, but you have set `indent-tabs-mode=nil`), bars may go missing. You should ideally pick _one_ indentation-style (tabs or spaces) per mode and stick to it for all files in that mode, but see [dtrt-indent](https://github.com/jscheid/dtrt-indent) for a package that can adapt this variable by examining the [...] +Note that some modes explicitly enable or disable `indent-tabs-mode`. If the value of that variable does not match the actual indentation used in a file (e.g. file is indented with tabs, but you have set `indent-tabs-mode=nil`), bars may go missing. You should ideally pick _one_ indentation-style (tabs or spaces) per mode and stick to it for all files in that mode, but see [dtrt-indent](https://github.com/jscheid/dtrt-indent) for a package that can adapt this variable by examining the [...] ## Current Depth Highlight -`indent-bars` can highlight the bar at the current depth, and supports a few different ways to determine which bar gets selected for highlight (see `indent-bars-highlight-selection-method`): +`indent-bars` can highlight the bar at the current depth, and supports a few different ways to determine which bar gets selected for highlight based on point. To configure this behavior, you can set `indent-bars-highlight-selection-method` to: 1. `nil`: The simplest version selects the depth of the last-visible bar on the current line for highlight. -2. `on-bar`: The old default, which selects the depth of the last visible bar _or_ the "unseen" bar that the first non-blank character on the current line "covers up". -3. `context`: The new default, a blend of these two methods. It selects the last-visible bar _unless_ an adjacent non-blank line (above or below) is indented deeper by at least one indent spacing, in which case the `on-bar` approach is used. +2. `on-bar`: The old default, which selects the "unseen" bar that the very first non-blank character on the current line "covers up", or if no such bar exists, the last visible bar. +3. `context`: The new default, a blend of these two methods. It selects the last-visible bar (à la `nil`), _unless_ an adjacent non-blank line (above or below) is indented deeper by at least one level, in which case the `on-bar` approach is used. -Experiment with these to see what you prefer. +Experiment with these to see which you prefer. ## Tree-sitter Details -`indent-bars` can optionally use tree-sitter in supported files to enable several features: +`indent-bars` can optionally use `tree-sitter` in supported files to enable several features: -1. **Scope Focus**: The current tree-sitter scope can be _focused_, with out-of-scope bars de-emphasized or in-scope bars emphasized (or actually, styled however you want). This can be configured by [specifying matching "scope"](#configuring-tree-sitter) node types (e.g. functions, blocks, etc.) for each language of interest. The innermost node (covering sufficient lines) will then be rendered distinctly from _out-of-scope_ bars. +1. **Scope Focus**: The current `tree-sitter` scope can be _focused_, with out-of-scope bars de-emphasized or in-scope bars emphasized (or actually, styled however you want). This can be configured by [specifying matching "scope"](#configuring-tree-sitter) node types (e.g. functions, blocks, etc.) for each language of interest. The innermost node (covering sufficient lines) will then be rendered distinctly from _out-of-scope_ bars. 1. **Selective Blank Line Display**: By default, `indent-bars` displays bars on blank lines (though this can be [configured](#bar-setup-and-location)), so that they remain continuous. It can be nice to omit the display of blank lines bars at the top structural level (e.g. in a _module_), to make divisions between top-level constructs more visible. Tree-sitter can help `indent-bars` identify those lines. -1. **Wrap Detection**: It can be useful to prevent excess bars inside wrapped entities which move indent to "line things up." These include things like argument lists, literal dictionaries, or other heirarchical multi-line structures. Tree-sitter can help detect these and inhibit unwanted bars (but [see also](#bar-setup-and-location) `indent-bars-no-descend-string/list`, which do not require tree-sitter). +1. **Wrap Detection**: It can be useful to prevent excess bars inside wrapped entities which alter indent to "line things up." These include things like argument lists, literal dictionaries, or other heirarchical multi-line structures. Tree-sitter can help detect these and inhibit unwanted bars (but [see also](#bar-setup-and-location) `indent-bars-no-descend-string/list`, which do not require tree-sitter). > [!NOTE] > `indent-bars`' tree-sitter capabilities require Emacs 29 or later built with > tree-sitter support, and the appropriate tree-sitter grammars installed for > your languages of interest. Additional node type configuration by language > is required; see below.