[elpa] externals/indent-bars def1e3e395 303/431: README: document v0.5 release

[ELPA Syncer]

branch: externals/indent-bars
commit def1e3e3955d88839f69a6f9936c3c67986377bf
Author: JD Smith <93749+jdtsmith@users.noreply.github.com>
Commit: JD Smith <93749+jdtsmith@users.noreply.github.com>

    README: document v0.5 release
---
 README.md | 159 +++++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 100 insertions(+), 59 deletions(-)

diff --git a/README.md b/README.md
index 49502a044a..aeb6895bed 100644
--- a/README.md
+++ b/README.md
@@ -2,23 +2,28 @@
 
 <img align="right" width="450" alt="image" 
src="https://github.com/jdtsmith/indent-bars/assets/93749/776e9c09-a3ef-41af-8237-dfe3f62aa48b";>
 
-This package provides vertical indentation _guide bars_, with the following 
features:
-
-- Supports both space and tab-based indentation.
-- Uses stipple face properties with font-lock for ultra-fast performance 
(simply: *faces on spaces*).
+This package provides indentation _guide bars_ enhanced by tree-sitter:
+
+- Uses stipple face properties with font-lock for fast performance.
+- Optional tree-sitter support, including highlighting a configurable active 
_scope_, among [other features](#tree-sitter).
+- Supports either space or tab-based indentation, learning indentation spacing 
from the active mode.
+- Bar appearance is _highly_ configurable: color, blending, width, position 
within the character, vertical fill/blank pattern, even zigzag (see 
[examples](examples.md)).
+- Bars can have optional depth-based coloring, with a cyclical color palette 
you can customize.
+- Fast current-depth bar highlighting with configurable bar color and/or 
appearance changes.
+- Bars can be drawn on blank lines.
+- Bar depth can be held constant inside multi-line strings and lists. 
 - Works in the terminal, using a vertical bar character.
-- Learns your buffer indentation spacing from the active mode.
-- Bar colors can blend with the frame background to reduce intrusiveness.
-- Bar appearance is highly configurable: width, position within the character, 
vertical fill/blank pattern, even zigzag (see [examples](examples.md)).
-- Bars have optional depth-based coloring, with a customizable cyclical color 
palette.
-- Font size changes are handled automatically.
-- Fast current-depth bar highlighting with bar color and/or appearance changes.
-- Blank line support.
-- Optional tree-sitter support, for context-aware bar depth in strings, 
wrapped entities like function arguments, and top level blank lines.
 
 ## What's New
 
-- v0.1: Initial stipple-based indentation.
+- v0.5: A major update with many new features and improvements.
+  - Stipples are now free from artifacts when showing the same buffer in 
multiple windows.
+  - Position-aware tree-sitter _scope_ with completely configurable 
out-of-scope styling.
+  - Theme-awareness: bar styling gets updated on theme change (e.g. for 
depth-based colors).
+  - Two new highlight selection "methods" including a new default ("context").
+  - Inhibit string and list bar descent even without treesitter using Emacs' 
syntax capabilities.
+- v0.2.2:
+  - Rate-limit updates of the current highlight depth; see 
`indent-bars-depth-update-delay`. 
 - v0.2: 
    - ability to configure the starting column (including col 0)
    - Support for tab-based indent modes
@@ -26,8 +31,7 @@ This package provides vertical indentation _guide bars_, with 
the following feat
    - tree-sitter context-aware bar depth
    - additional mode support: `go-mode`, `go-ts-mode`, `cobol-mode`
    - other minor improvements
-- v0.2.2:
-  - Rate-limit updates of the current highlight depth; see 
`indent-bars-depth-update-delay`. 
+- v0.1: Initial stipple-based indentation.
 
 # FAQ's
 
@@ -67,14 +71,19 @@ To clone with `use-package` and `straight`:
 ```elisp
 (use-package indent-bars
   :load-path "~/code/emacs/indent-bars"
+  :config
+  (require 'indent-bars-ts)            ; not needed with straight
   :custom
   (indent-bars-treesit-support t)
-  (indent-bars-no-descend-string t)
   (indent-bars-treesit-ignore-blank-lines-types '("module"))
-  (indent-bars-treesit-wrap '((python argument_list parameters ; for python, 
as an example
-                                     list list_comprehension
-                                     dictionary dictionary_comprehension
-                                     parenthesized_expression subscript)))
+  ;; Add other languages as needed
+  (indent-bars-treesit-scope '((python function_definition class_definition 
for_statement
+         if_statement with_statement while_statement)))
+  ;; wrap may not be needed if no-descend-list is enough
+  ;;(indent-bars-treesit-wrap '((python argument_list parameters ; for python, 
as an example
+  ;;                                 list list_comprehension
+  ;;                                 dictionary dictionary_comprehension
+  ;;                                 parenthesized_expression subscript)))
   :hook ((python-base-mode yaml-mode) . indent-bars-mode))
 ```
 
@@ -85,7 +94,7 @@ See [tree-sitter](#tree-sitter), and also the [Wiki 
page](https://github.com/jdt
 > [!IMPORTANT]
 > For `indent-bars` to display fancy guide bars, your port and version of 
 > emacs must correctly display the `:stipple` face attribute.  **Most do**, 
 > but some do not.
 
-`indent-bars` can also be used *without stipples*, drawing a simple vertical 
character (like `│`) instead.  It automatically does this in non-graphical 
displays (terminals), but can optionally be configured to always do so; see 
[Character Display](#character-display).
+`indent-bars` can also be used *without stipples*, drawing a simple vertical 
character (like `│`) instead.  It automatically does this in non-graphical 
displays (terminals), but can optionally be configured to do so always; see 
[Character Display](#character-display).
 
 Known `:stipple` support, by Emacs build:
 
@@ -108,68 +117,109 @@ See also [Testing Stipples](#testing-stipples).
 
 See some [examples](examples.md) with relevant settings.
 
-The main customization variables:
-       
+The main customization variables are categorized below.  See the documentation 
of each variable for more details.
+
+## Bar shape and size
 - `indent-bars-width-frac`: The fractional width of the bar (0-1, in terms of 
fraction of a single character's width).
 - `indent-bars-pad-frac`: The fractional padding offset of the bar from the 
left edge of the character. 
 - `indent-bars-pattern`: A string specifying the vertical structure of the bar 
(space=blank, non-space=filled).  Scaled to the height of one character.
 - `indent-bars-zigzag`: A fractional left-right *zigzag* to apply to 
consecutive groups of identical non-space characters in `pattern`.
+
+## Bar color and highlighting
 - `indent-bars-color`: The main bar color, either a color name or face, from 
which foreground or background color will be taken.  Also used to set a 
`:blend` factor, to blend colors into the frame's background color.
 - `indent-bars-color-by-depth`: How and whether to alter the color of the 
indent bars by indentation depth.  Defaults to using the foreground of the 
`outline-*` faces.
+
+## Current Depth highlighting
 - `indent-bars-highlight-current-depth`: How and whether to highlight the bars 
at the indentation depth of the current line.  The current depth bar can change 
color (including blending with the pre-existing color), as well as structure 
(size, pad, pattern, zigzag).
-- `indent-bars-starting-column`: column to use for the first bar.  Can be set 
in special modes which start at an unusual fixed offset, or set to 0 to get  
"column 0" bars.
+- `indent-bars-highlight-selection-method`: Method used to select which bar is 
highlighted.  The default (`'context`) considers surrounding lines for a more 
natural bar selection.  
+- `indent-bars-depth-update-delay`: Delay in seconds after which depth 
highlighting occurs. 
+
+## Bar setup and location
+- `indent-bars-starting-column`: column to use for the first bar.  Can be set 
in special modes which start at an unusual fixed offset, or set to 0 to get 
"column 0" bars.
 - `indent-bars-spacing-override`:  Normally the number of spaces for 
indentation is automatically discovered from the mode and other variables.  If 
that doesn't work for any reason, it can be explicitly set using this variable.
 - `indent-bars-display-on-blank-lines`: Whether to display bars on blank lines.
+- `indent-bars-no-descend-string`: Whether to inhibit increasing depth inside 
of strings. 
+- `indent-bars-no-descend-list`: Whether to inhibit increasing depth inside of 
lists. 
+
+## Character-based bars and terminal
 - `indent-bars-prefer-character`: Use *characters* to display the vertical bar 
instead of stipples.  This occurs automatically on non-graphical displays 
(terminals), but this variable can be used to always prefer character-based 
display.
 - `indent-bars-no-stipple-char`: The character to use when stipples are 
unavailable or disabled. Defaults to the vertical box character `│`.  Other 
good options include `┃`, `┋`, and `║`.
 - `indent-bars-no-stipple-char-font-weight`: Optional font weight to use for 
the face displaying the no-stipple character.
 - `indent-bars-unspecified-bg|fg-color`: Colors to use for the frame 
background and default foreground when they are unspecified (e.g. in 
terminals).  If you intend to use `indent-bars` in the terminal, set to the 
terminal background/foreground colors you use. 
+
+## Treesitter support
 - `indent-bars-treesit-support`: Whether to use tree-sitter (if available) to 
help determine appropriate bar depth.
-- `indent-bars-treesit-wrap`: A mapping of language to tree-sitter wrap types, 
to avoid adding extra bars e.g. in wrapped function arguments.
-- `indent-bars-treesit-ignore-blank-lines-types`: A list of tree-sitter node 
types to inhibit styling blank lines at, like "module". 
-- `indent-bars-no-descend-string`: Whether to inhibit increasing depth inside 
of (tree-sitter determined) strings. 
+- `indent-bars-treesit-scope`: A mapping of language to tree-sitter scope node 
types, for local scope highlight.
+- `indent-bars-treesit-scope-min-lines`: The minimum number of lines a scope 
node must occupy to be considered a valid scope.
+- `indent-bars-treesit-wrap`: A mapping of language to tree-sitter wrap types, 
to avoid adding extra bars e.g. in wrapped function arguments.  Note that this 
is considered only after the `no-descend` options above.
+- `indent-bars-treesit-ignore-blank-lines-types`: A list of tree-sitter node 
types inside of which inhibit styling blank lines at, like "module". 
+- `indent-bars-treesit-update-delay`: Delay in seconds for updating the 
treesitter scope highlight.
 
+## Out-of-scope alternate styling variables
+If tree-sitter scope is active (`indent-bars-treesit-scope`), the settings 
above apply only to the _in scope_ text. To permit configuring the appearance 
of the out-of-scope bars, a parallel set of custom variables with 
`indent-bars-ts-` prefixes are created.
 
+These can be used in the same manner as above to _fully_ configure the 
appearance of the "out-of-scope" bars (i.e. bars outside the custom tree-sitter 
scope), including depth highlighting.  Note that scope highlighting is 
completely independent of depth highlighting.  The `ts` parallel variables for 
out-of-scope styling are:
 
-See the documentation of each variable for more details.
+- `indent-bars-ts-color` `inherit`
+- `indent-bars-ts-width-frac`
+- `indent-bars-ts-pad-frac`
+- `indent-bars-ts-pattern`
+- `indent-bars-ts-zigzag`
+- `indent-bars-ts-no-stipple-char-font-weight`
+- `indent-bars-ts-color-by-depth` [`inherit`]
+- `indent-bars-ts-highlight-current-depth` [`inherit`]
+
+Each of these parallel variables has an equivalent form to their equivalent 
non-`ts` version (the "parent" variable), with two difference:
+
+1. Some (marked with [`inherit`] above) can be specified as 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) means 
that any `:key` values not specified are inherited from the "parent" customize 
variable.  `no-inherit` means to omit any missing key values.
+2. For any non-`:key` type values, the specific value `'unspecified` can be 
set to specify using the parent's value for that slot.
+
+For example, a setting of:
+
+`indent-bars-ts-color = '(inherit unspecified :blend 0.15)` means to use the 
color from the parent variable `indent-bars-color`, set `:blend` to 0.15, and 
inherit any other missing keyword values from from `indent-bars-color` for 
out-of-scope bar coloring.
+
+The easiest way to configure inheritance and unspecified values in the `ts` 
variables is via customize.
 
 # Details and Caveats
 
 ## Speed
 
-`indent-bars` was partially motivated by the inefficiency of older indentation 
highlight modes, and is designed for speed.  It uses stipples (fixed bitmap 
patterns) and font lock for fast and efficient bar drawing -— *faces on 
spaces*.  Highlighting the current indentation level is essentially free, since 
it works by 
[remapping](https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Remapping.html)
 the relevant face.
+`indent-bars` was in part motivated by the inefficiency of older indentation 
highlight modes, and is designed for speed.  It uses stipples (fixed bitmap 
patterns) and font lock for fast and efficient bar drawing -— *faces on 
spaces*.  Highlighting the current indentation level is essentially free, since 
it works by [filtered 
remapping](https://www.gnu.org/software/emacs/manual/html_node/elisp/Face-Remapping.html)
 the relevant face.
 
-The heaviest operations (though still quite efficient) are **tree-sitter** 
support, and  **blank-line highlighting**.  If you experience any speed issues, 
these are the first settings to experiment with turning off.  Note that in 
recent versions, a timer was added to rate-limit current-depth highlighting, 
simply to prevent "rapid flashing" during fast scrolling or other fast 
movements.  It's safe to disable this without any performance impact (set 
`indent-bars-depth-update-delay=0`). 
+The heaviest operations are **tree-sitter** support (especially scope 
highlighting), and **blank-line highlighting**.  If you experience any speed 
issues, these are the first settings to experiment with.  Using with tab-based 
indentation is also slightly slower than with space-based.
 
-## Indentation
+Both indentation-depth highlighting and current-tree-sitter-scope highlighting 
are protected by timers to avoid unnecessary loads (e.g. when pixel-scrolling). 
 Note that indentation-depth highlighting is _very_ fast and can safely be set 
to 0 seconds (though bars will then flash very fast as you scroll).  
Tree-sitter scope requires querying the tree-sitter core, which can be somewhat 
slower, so be careful setting its timer too low.
 
-`indent-bars` works either with space-based indentation (i.e. 
`indent-tabs-mode=nil`) or with tab-based.  If possible, prefer space 
indentation, as it is faster.  Note that some modes explicitly enable or 
disable `indent-tabs-mode`.
+## Indentation
 
-## Tree-sitter
+`indent-bars` works with either space- or tab-based indentation.  If possible, 
prefer space indentation, as it is faster.  Note that some modes explicitly 
enable or disable `indent-tabs-mode`.
 
-`indent-bars` can optionally use tree-sitter in supported files to improve the 
calculation of bar depth.  For example, many modes wrap function calls and 
definitions to align parameters with the opening `(`.  With the help of 
tree-sitter, `indent-bars` can avoid adding unwanted additional bars in these.  
It can also be used to avoid extra depth in strings, and to tweak the behavior 
of blank line display.
+## Current Depth Highlight
 
-I.e. turn this:
+`indent-bars` can highlight the bar at the current depth, and supports a few 
different ways to determine which bar that is (`Variables 
indent-bars-highlight-selection-method`).  The simplest is selecting the 
last-visible bar on the current line.  The old default was `on-bar`, which 
selects the "unseen" bar that the text on the current line starts on.  The new 
default is `'context`, which selects the last-visible bar unless an adjacent 
no-blank line is indented deeper by at least one inde [...]
 
-<img width="580" alt="Untitled" 
src="https://github.com/jdtsmith/indent-bars/assets/93749/f1cb2489-92ee-443d-b941-6237b386ca6f";>
+## Tree-sitter
 
-into this:
+`indent-bars` can optionally use tree-sitter in supported files to add several 
significant features:
 
-<img width="580" alt="Untitled 2" 
src="https://github.com/jdtsmith/indent-bars/assets/93749/b0c26c5b-6b38-475f-9bb8-9f1b1f5e54f0";>
+1. **Scope Highlighting**: The current tree-sitter scope can be configured by 
specifying matching node types.  The innermost node (covering sufficient lines) 
will then be rendered using the normal bar color and style.  Bars which are 
_out-of-scope_ have alternative styling applied.  See configuration, above.
+1. **Blank Line Display**: It can be nice to omit the display of bars on blank 
lines at the top level (e.g. in a _module_).  Tree-sitter can help show those 
lines.
+1. **Wrap Detection**: It can be useful to prevent the drawing of many bars in 
wrapped entities like argument lists or literal dictionaries.  Tree-sitter can 
help detect these and inhibit these unwanted bars (see also 
`indent-bars-no-descend-string/list`, which do not require tree-sitter).
 
-**Note**: This requires Emacs 29 built with tree-sitter support, and the 
appropriate tree-sitter grammars installed for languages of interest.
+> [!NOTE]
+> 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 required; see 
below.
 
 ### Configuring tree-sitter
 
-The main thing to do is configure `indent-bars-treesit-wrap` with the node 
types that lead to unwanted additional bars do their wrapping indentation 
behavior.  I recommend starting with the minimal possible set.  
+Simply configure `indent-bars-treesit-scope` with the node types for which 
"local scope" highlighting is of interest.  This must be done for each language 
you use.  This scope could be as granular as classes and functions, or 
including detailed block statements.   `indent-bars-treesit-wrap` can be 
configured in a similar manner, if desired.  I recommend starting with the 
minimal possible set of node types, adding as needed.
 
-The easiest way to discover the node types of interest is to `M-x 
treesit-explore-mode`, then highlight the beginning of a line with too many 
bars, and look in the `treesitter explorer` buffer which pops up for the names 
of obvious nodes in the tree.  Add these types to `indent-bars-treesit-wrap` 
for the language of interest, then `M-x indent-bars-reset` and see how you did. 
 You can do something similar for 
`indent-bars-treesit-ignore-blank-lines-types` (which, please note, are 
configur [...]
+The easiest way to discover the node types of interest (in a buffer with 
working treesit support) is to `M-x treesit-explore-mode`. Then simply 
highlight the beginning of a line of interest, and look in the `treesitter 
explorer` buffer which pops up for the names of obvious nodes in the tree.  Add 
these types to `indent-bars-treesit-scope/wrap` for the language of interest, 
then `M-x indent-bars-reset` and see how you did.  You can do something similar 
for `indent-bars-treesit-ignore-bla [...]
 
-Please document good tree-sitter settings for other langauges in the 
[Wiki](https://github.com/jdtsmith/indent-bars/wiki/indent%E2%80%90bars-config-Wiki#tree-sitter-config).
+Please document good tree-sitter settings for other languages in the 
[Wiki](https://github.com/jdtsmith/indent-bars/wiki/indent%E2%80%90bars-config-Wiki#tree-sitter-config).
 
 ## Moving by columns
 
-If `indent-bars-display-on-blank-lines` is set, the newline at the end of 
blank lines has a `'display` property set to show the bars.  Emacs does not 
deal correctly with display properties containing newlines when moving by 
columns.  This is not normally a problem, but in one instance it is a nuisance: 
evil tries to "preserve" column during line moves, so can trigger this emacs 
misfeature.  The symptom is that point jumps a line and moves over as you move 
down with evil.  A solution is [ [...]
+If `indent-bars-display-on-blank-lines` is set, the newline at the end of 
blank lines may have a `'display` property set to show the bars.  Emacs does 
not deal correctly with display properties containing newlines when moving by 
columns.  This is not normally a problem, but in one instance it is a nuisance: 
`evil-mode` tries to "preserve" column during line moves, so can trigger this 
emacs misfeature.  The symptom is that point jumps a line and moves over as you 
move down with evil.  A s [...]
 
 ## Display
 
@@ -200,21 +250,11 @@ This should then look something like (note the blue 
vertical bars):
 
 <img width="668" alt="image" 
src="https://github.com/jdtsmith/indent-bars/assets/93749/dd0f65f5-3cdc-4865-a66d-41365cecadd0";>
 
-If you determine that stipples do not work in your Emacs, consider upgrading 
to a version which supports them, reporting the bug, or setting 
`indent-bars-prefer-character=t`.
+If you determine that stipples do not work in your version of Emacs, consider 
upgrading to a version which supports them, reporting the bug, or setting 
`indent-bars-prefer-character=t`.
 
 #### Per-buffer stipple offsets
-To get the stipple bars to appear in the correct location within their column, 
`indent-bars` must consider the starting horizontal pixel position of the 
current window, and "rotate" the stipple pattern accordingly.  It does this 
automatically, per buffer, so you shouldn't ever notice problems, even when 
re-sizing or re-arranging windows, changing font size, etc.
-
-There is one rare corner case, however: showing the *same buffer* side by side 
in Emacs versions which support pixel-level window width/offsets (e.g. 
emacs-mac).  This can lead to unexpected bar positions in the non-active 
buffer, since the stipple offset in the remapped face applies *per-buffer*, not 
per-window.  I.e. it can't be correct for the same buffer in left and right 
windows *at the same time*.
-
-Options are:
-
-1. Living with it (simpler stipple patterns may help).
-2. Using a build of emacs that always starts windows on the character boundary.
-3. Switching to [character-based bars](#character-display).
-4. (For Emacs >=29[^2]) instead of visiting the same buffer, cloning an 
indirect buffer (which has other advantages, like an independent region).
 
-[^2]: Note that Emacs 28 and earlier have a bug which results in cloned 
buffers sharing the same face remapping list as their parent; this is fixed in 
Emacs 29.
+To get the stipple bars to appear in the correct location within their column, 
`indent-bars` must consider the starting horizontal pixel position of the 
current window, and "rotate" the stipple pattern accordingly.  It does this 
automatically, per buffer, so you shouldn't ever notice problems, even when 
re-sizing or re-arranging windows, changing font size, etc.  Until v0.5, 
showing the *same buffer* side by side in Emacs versions which support 
pixel-level window width/offsets could lead [...]
 
 ### Character display
 
@@ -226,14 +266,14 @@ Note that in mixed gui/terminal sessions of the same 
Emacs process, you need to
 
 #### Advantages of stipples
 
-- Custom appearance and position within the character is possible — 
[examples](examples.md).
+- Highly customized appearance and position within the character is possible — 
[examples](examples.md).
 - Fastest option: does not need to apply display properties for normal lines 
with space-based indentation.
 - Results in continuous lines even when `line-spacing` is non-nil (vs. gaps 
with box characters and additional line spacing).
 
 #### Advantages of character bar display
 
 - Works equally for terminal and GUI.
-- Works even for emacs ports which do not support or mishandle stipple display 
(see [Compatibility](#compatibility)).
+- Works even for emacs ports which do not support or mis-handle stipple 
display (see [Compatibility](#compatibility)).
 
 # Related Packages
 
@@ -251,9 +291,10 @@ None of the existing packages:
 2. had enough guide appearance configurability
 3. were able to support depth-based coloring
 4. offered robust support for guides on blank lines
+5. had tree-sitter capabilities
 
-### Acknowledgements
+### Acknowledgments
 
-I'm grateful for advice and input on the design of `indent-bars` from Eli 
Zaretski, Stefan Monnier, Dmitry Gutov and many other who opened issues and PRs.
+I'm grateful for in-depth advice and input on the design of `indent-bars` from 
Eli Zaretski, Stefan Monnier, Dmitry Gutov and many other who opened issues and 
PRs.
 
 
[highlight-indentation-mode](https://github.com/antonj/Highlight-Indentation-for-Emacs)
 was a source of good ideas, and `indent-bars` adapts the indentation guessing 
function from this mode.  The original idea of using stipples for "better" 
indent-bars came from [this comment by 
@vlcek](https://github.com/antonj/Highlight-Indentation-for-Emacs/issues/16#issuecomment-48593300).