Re: [ELPA] New package: breadcrumb.el

[Philip Kaludercic]

João Távora <joaotavora@gmail.com> writes:

> On Tue, Sep 5, 2023 at 4:58 PM Jonas Bernoulli <jonas@bernoul.li> wrote:
>>
>> João Távora <joaotavora@gmail.com> writes:
>>
>> > Hi all
>> >
>> > I'd like to add my package "breadcrumb" to GNU ELPA.
>> > [...]
>> > Here's a link to the project (which has a screenshot)
>> > https://github.com/joaotavora/breadcrumb
>>
>> Another package by that name already exists, but it wasn't touched in
>> 13 years: https://github.com/pheaver/breadcrumb.
>>
>> If you weren't aware of this and would like to avoid taking over an
>> existing name in the future (or be aware that you are doing that, and
>> possibly reach out to the author of the older implementation), you could
>> consult my list at https://emacsmirror.net/stats/upstreams.html, which
>> lists all packages in the Emacsmirror and Emacsattic, which is a
>> superset of packages in GNU ELPA, NonGNU ELPA and MELPA (modulo recent
>> additions).
>
> Oops, I missed that.  What does it do.
>
>> Unrelated, but since I looked at your package: Please use just two
>> semicolons inside library commentaries (and in other "non-heading"
>> comments) .  Otherwise all the lines that match "^;;;+ ." are treated
>> as headings by outline-minor-mode.  (You can of course continue to use
>> ";;;; subheading".)
>
> Not sure I 100% understand what you mean, but if you propose a
> patch I'll happily merge it.

I believe Jonas is proposing a change along these lines,

diff --git a/breadcrumb.el b/breadcrumb.el
index cf527afacc..a6c1a868d7 100644
--- a/breadcrumb.el
+++ b/breadcrumb.el
@@ -21,78 +21,77 @@
 ;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
 ;;; Commentary:
-;;;
+
 ;;;; Usage:
-;;;
-;;; Breadcrumbs are sequences of short strings indicating where you
-;;; are in some big tree-like maze.
-;;;
-;;; To craft these strings, this library uses the maps provided by
-;;; project.el and Imenu, respectively.  Project breadcrumbs shows you
-;;; the current buffer's path in a large project.  Imenu breadcrumbs
-;;; show the current position of point in the buffer's nested
-;;; structure of programming constructs (for example, a specific
-;;; functions within multiple C++ nested namespaces).
-;;;
-;;; To use this library:
-;;;
-;;; * `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
-;;;
-;;;     (:eval (breadcrumb-imenu-crumbs))
-;;;
-;;;   and
-;;;
-;;;     (:eval (breadcrumb-project-crumbs))
-;;;
-;;;  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
-;;; `breadcrumb-imenu-max-length', `breadcrumb-project-max-length',
-;;; `breadcrumb-imenu-crumb-separator', and
-;;; `breadcrumb-project-crumb-separator'.
-;;;
-;;; The structure each 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.
-;;;
-;;;; Implementation notes:
-;;;
-;;; This _should_ be faster than which-func.el due some caching
-;;; strategies.  One of these strategies occurs in `bc--ipath-alist',
-;;; which takes care not to over-call `imenu--make-index-alist', which
-;;; could be slow (in fact very slow if an external process needs to
-;;; be contacted).  The variable `breadcrumb-idle-delay' controls
-;;; that.  Another cache occurs in `bc--ipath-plain-cache' second is
-;;; just a simple "space-for-speed" cache.
-;;;
-;;; Breadcrumb uses the double-dashed Imenu symbols
-;;; `imenu--index-alist' and `imenu--make-index-alist'.  There's
-;;; really no official API here.  It's arguable that, despite the
-;;; name, these aren't really internal symbols (the much older
-;;; which-func.el library makes liberal use of them, for example).
-;;;
-;;;; Todo:
-;;;
-;;; Make more clicky buttons in the headerline to do whatever
-;;;
+
+;; Breadcrumbs are sequences of short strings indicating where you
+;; are in some big tree-like maze.
+;;
+;; To craft these strings, this library uses the maps provided by
+;; project.el and Imenu, respectively.  Project breadcrumbs shows you
+;; the current buffer's path in a large project.  Imenu breadcrumbs
+;; show the current position of point in the buffer's nested
+;; structure of programming constructs (for example, a specific
+;; functions within multiple C++ nested namespaces).
+
+;; To use this library:
+
+;; * `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
+;;
+;;     (:eval (breadcrumb-imenu-crumbs))
+;;
+;;   and
+;;
+;;     (:eval (breadcrumb-project-crumbs))
+;;
+;;  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
+;; `breadcrumb-imenu-max-length', `breadcrumb-project-max-length',
+;; `breadcrumb-imenu-crumb-separator', and
+;; `breadcrumb-project-crumb-separator'.
+
+;; The structure each 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.
+
+;;; Implementation notes:
+
+;; This _should_ be faster than which-func.el due some caching
+;; strategies.  One of these strategies occurs in `bc--ipath-alist',
+;; which takes care not to over-call `imenu--make-index-alist', which
+;; could be slow (in fact very slow if an external process needs to
+;; be contacted).  The variable `breadcrumb-idle-delay' controls
+;; that.  Another cache occurs in `bc--ipath-plain-cache' second is
+;; just a simple "space-for-speed" cache.
+
+;; Breadcrumb uses the double-dashed Imenu symbols
+;; `imenu--index-alist' and `imenu--make-index-alist'.  There's
+;; really no official API here.  It's arguable that, despite the
+;; name, these aren't really internal symbols (the much older
+;; which-func.el library makes liberal use of them, for example).
+
+;;; Todo:
+
+;; Make more clicky buttons in the headerline to do whatever
 
 ;;; Code:
 (require 'cl-lib)
@@ -100,7 +99,7 @@
 (require 'project)
 
 
-;;; Customization options
+;;;; Customization options
 
 (defgroup breadcrumb nil
   "One-liner indication of where you are in the maze."
@@ -147,8 +146,8 @@ percentage of `window-width'."
   "Face for the project leaf crumb in breadcrumb project path.")
 
 
-;;; "ipath" management logic and imenu interoperation
-;;;
+;;;; "ipath" management logic and imenu interoperation
+
 (cl-defun bc--bisect (a x &key (from 0) (to (length a)) key from-end)
   "Compute index to insert X in sequence A, keeping it sorted.
 If X already in A, the resulting index is the leftmost such
@@ -244,7 +243,7 @@ These structures don't have a `breadcrumb-region' property 
on."
     imenu--index-alist))
 
 
-;;; Higher-level functions
+;;;; Higher-level functions
 
 ;; FIXME: Why do I need to put these key definitiosn in special
 ;; variables?

You can see the effect this as in practice by enabling
outline-minor-mode and running M-x outline-hide-body before and after
applying the changes.

> João