[elpa] externals/indent-bars 7b72bdb752 048/431: Initial README info

[ELPA Syncer]

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

    Initial README info
---
 README.md | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 74 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index d4a16ecf92..7e26be9756 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,75 @@
 # indent-bars
-Performant and configurable indentation highlighting for Emacs
+
+Fast, configurable indentation guide-bars for Emacs.
+
+<img align="center" width="514" alt="ib_default" 
src="https://github.com/jdtsmith/indent-bars/assets/93749/4f652554-bede-4aa6-bdbc-233ec843d782";>
+
+This package draws vertical indentation vertical bars with the following 
features:
+
+- Uses stipple face properties with font-lock for ultra-fast performance 
(simply: *faces on spaces*).
+- Learns your buffer indentation spacing from the mode.
+- Bar colors can be blended with the frame background color, to reduce their 
intrusiveness.
+- Bar appearance is highly configurable: width, position within the character, 
vertical fill/blank pattern, even zigzag (see [examples](examples.md)).
+- Optional depth-based coloring, with a customizable cyclical palette.
+- Properly handles font size changes.
+- Optional zero-cost current-depth bar highlighting, with bar color and/or 
appearance changes.
+- Optional support for drawing bars on blank lines.
+
+# Why?
+
+There are ([many](#related-packages)) existing packages that provide 
indentation highlighting/guides.  But none:
+
+1. were fast enough with large files (including with current depth highlight)
+2. had enough guide appearance configurability
+3. were able to support depth-based coloring
+
+# Install/config
+
+Not yet in a package database; simply clone and point `use-package` at the 
correct path (or use 
[straight](https://github.com/radian-software/straight.el), etc.).
+
+```elisp
+(use-package indent-bars
+  :load-path "~/code/emacs/indent-bars"
+  :hook ((python-mode yaml-mode) . indent-bars-mode)) ; or whichever modes you 
prefer
+```
+
+# Customization
+       `M-x customize-group indent-bars` is the easiest way to customize 
everything about the appearence and function of `indent-bars`.  Note: when 
changing any of these variables while `indent-bars` is on, you must `M-x 
indent-bars-reset` in the buffers of interest to see the resulting changes.  
See some [examples](examples.md).
+       
+The main customization variables:
+       
+       - `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`.
+       - `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 the color into the frame background color.
+       - `indent-bars-color-by-depth`: How and whether to alter the color of 
the indent bars by depth.  Defaults to using the foreground colors of 
`outline-*` faces.
+       - `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-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.
+
+See the documentation of each variable for more details.
+
+# 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.  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.
+
+The heaviest operation (though still fairly efficient) is **blank-line 
highlighting**, since the indentation level of blank lines depends on their 
surrounding context, and strings must be allocated, styled, and used as 
`'display` properties.  If you experience any speed issues, this is the first 
setting to turn off. 
+
+## Indentation
+
+`indent-bars` only works with space-based indentation, i.e. 
`indent-tabs-mode=nil`.  Note that many modes enable this by default.
+
+## Stipples
+The fast *stipple* method used for drawing bars enables lots of [interesting 
patterns](examples.md).
+
+Stipples are repeating patterns anchored to the entire emacs frame.  
`indent-bars` basically "opens windows" on this fixed pattern to "reveal" the 
bars.  To get the bars in the right place, `indent-bars` must consider the 
starting horizontal pixel position of the current window, and adjust 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 corner case, however: showing the *same buffer* side by side can 
lead to unexpected bar positions in the non-active buffer, since the stipple 
offset in the remapped face applies *per-buffer*.  Options are living with 
this, or cloning an indirect buffer (which has other advantages, like an 
independent region).  Note that Emacs 28 and earlier have a bug which results 
in cloned buffers share the same face remapping list as their parent; this is 
fixed in Emacs 29.
+
+# Related Packages
+-[indent-guide](https://github.com/zk-phi/indent-guide): An older package that 
uses overlays with `|` characters.  Some reports of performance concerns.  
Incompatible with company and other related in-buffer modes.
+-[highlight-indentation-mode](https://github.com/antonj/Highlight-Indentation-for-Emacs):
 Uses overlays to draw indentation guides, and includes a current indentation 
mode.  Partial support for blank line guides.  `indent-bars` adapts the 
indentation guessing function from this mode.
+-[highlight-indent-guides](https://github.com/DarthFennec/highlight-indent-guides):
  a highly configurable mode for indentation highlight, with color and style 
options, as well as current depth highlighting.
+- 
[visual-indentation-mode](https://github.com/skeeto/visual-indentation-mode): 
Full character-based alternating color indentation guides.  Package is now 
archived.