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.
