[elpa] externals/breadcrumb eb7c97d414 04/18: Add a README.md and a screenshot

[ELPA Syncer]

branch: externals/breadcrumb
commit eb7c97d4147cbef60a3b51b26299ce5d39e1c356
Author: João Távora <joaotavora@gmail.com>
Commit: João Távora <joaotavora@gmail.com>

    Add a README.md and a screenshot
    
    * README.md: new file.
    
    * breadcrumb.el: Tweak.
    
    * screenshot.png: new file.
---
 README.md      |  62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 breadcrumb.el  |  15 +++++++-------
 screenshot.png | Bin 0 -> 53193 bytes
 3 files changed, 69 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..60715a65bd
--- /dev/null
+++ b/README.md
@@ -0,0 +1,62 @@
+# M-x breadcrumb-mode
+
+![screenshot](./screenshot.png)
+
+## Usage
+
+Breadcrumbs are sequences of short strings indicating where you are in
+some big tree-like maze that is probably your code.  Hopefully the
+screenshot above clears it up.
+
+* `M-x breadcrumb-mode` is global mode.  Will try to turn itself on
+  conservatively and only if there's a project.
+
+* `M-x breadcrumb-local-mode` is a buffer-local minor mode, if you
+  don't want the default heuristics for turning it on everywhere.
+   
+There's not much more to it.  Breadcrumb will try to query `imenu.el`
+and `project.el` for the best information.
+
+## Installation
+
+For now, just download the `breadcrumb.el` file and load it somehow.
+
+## More usage
+
+If you want some leet modeline you may also manually put the mode-line
+constructs
+
+```lisp
+(:eval (breadcrumb-imenu-crumbs))
+```
+
+and
+
+```lisp
+(:eval (breadcrumb-project-crumbs))
+```    
+
+in your settings of the `mode-line-format` or `header-line-format`
+variables.
+
+## Tweaks
+
+The shape and size of each breadcrumb groups may be tweaked via
+`breadcrumb-imenu-max-length`, `breadcrumb-project-max-length`,
+`breadcrumb-imenu-crumb-separator`, and
+`breadcrumb-project-crumb-separator`.
+
+The structure each of the breadcrumbs varies depending on whether
+either `project.el` and `imenu.el` (or both) can do useful things for
+your buffer.
+
+For Project breadcrumbs, this depends on whether `project.el`'s
+`project-current` can guess what project the current buffer belongs
+to.
+
+For Imenu breadcrumbs, this varies.  Depending on the major-mode
+author's taste, the Imenu tree (in variable `imenu--index-alist`) may
+have different structure.  Sometimes, minor mode also tweak the Imenu
+tree in useful ways.  For example, with recent Eglot (I think Eglot
+1.14+), managed buffers get extra region info added to it, which makes
+Breadcrumb show "richer" paths.
diff --git a/breadcrumb.el b/breadcrumb.el
index e678aa8b76..bcb27b99b4 100644
--- a/breadcrumb.el
+++ b/breadcrumb.el
@@ -1,4 +1,4 @@
-;;; breadcrumb.el --- imenu-based breadcrumb paths   -*- lexical-binding: t; 
-*-
+;;; breadcrumb.el --- project and imenu-based breadcrumb paths   -*- 
lexical-binding: t; -*-
 
 ;; Copyright (C) 2023  João Távora
 
@@ -35,12 +35,11 @@
 ;;;
 ;;; To use this library:
 ;;;
-;;; * M-x breadcrumb-local-mode.  A buffer-local minor-mode which
-;;;   puts Project and Imenu-derived breadcrumbs derived in the header
-;;;   line automatically.
-;;;
-;;; * M-x breadcrumb-mode.  A global version of the above.  Will try
-;;;   to turn itself on conservatively and only if there's a project.
+;;; * `M-x breadcrumb-mode` is a global mode.  Will try to turn itself
+;;;   on conservatively and only if there's a project.
+
+;;; * `M-x breadcrumb-local-mode` is a buffer-local minor mode, if you
+;;;    don't want the default heuristics for turning it on everywhere.
 ;;;
 ;;; * Manually put the mode-line constructs
 ;;;
@@ -50,7 +49,7 @@
 ;;;
 ;;;     (:eval (breadcrumb-project-crumbs))
 ;;;
-;;;  in your seettings of the `mode-line-format' or
+;;;  in your settings of the `mode-line-format' or
 ;;;  `header-line-format' variables.
 ;;;
 ;;; The shape and size of each breadcrumb groups may be tweaked via
diff --git a/screenshot.png b/screenshot.png
new file mode 100644
index 0000000000..b237cd99d2
Binary files /dev/null and b/screenshot.png differ