Cycling states inconsistent with descriptions

[yuhan0]

According to the docstring of bicycle-cycle-global:

TOC: Show all headings, without treating top-level code blocks as sections.

and bicycle-cycle-local,

CHILDREN: Show the current heading and recursively those of all subsections, [...]

Both imply that all nested headings will be shown, except for code blocks. However, in both cases only one level of child subheadings is expanded.

Eg. given the following emacs-lisp buffer:

;;; h1
;;;; h2
;;;;; h3
(code)

• Cycle to the TOC global state. Expected visible headings: h1, h2, h3 Actual: h1, h2

• From the first line (h1), cycle to the CHILDREN state. Expected visible headings: h1, h2, h3 Actual: h1, h2

It's not clear if this is the intended behavior and the docstring is incorrectly written, or if it is a bug with the implementation.

[yuhan0]

Additional Context:

There are 5 meaningful visibility states for a given heading, given bicycle's differentiation of "code block" outlines:

H    = Current heading (level N)
H+   = Direct children headings (levels N, N+1) 
H*   = All nested headings (levels N, N+1 N+2, ..., except code blocks)
H*C  = All headings, plus the first lines of code blocks
H*C* = All contents unfolded

Of these, Bicycle's local cycling uses 4 states, where only CHILDREN is ambiguous:

FOLDED:   H
CHILDREN: H+ (impl) / H* (docstring)
BRANCHES: H*C
SUBTREE:  H*C*

The current impl. and naming agrees with org-mode's TAB cycling, which has only 3 states.

FOLDED:   H
CHILDREN: H+
SUBTREE:  H*C*

---

Similarly, for global cycling the visibility of each top level headline can be specified as:

OVERVIEW: H
TOC:      H+ (impl) / H* (docstring)
TREES:    H*C
ALL:      H*C*

Where only the TOC state is ambiguous.

Compare to org-global-cycle's 3 states, where this time the middle state shows all nested subheadings.

OVERVIEW: H
CONTENTS: H*
SHOW ALL: H*C*

[tarsius]

Thanks for the detailed report. I probably won't look into it any time soon, but this does indeed sound like it needs some work. It might be worth implementing more states, or at least support the same styles for local and global cycling. Or maybe I should just clarify the documentation. I am concentrated on other packages right now, so even just deciding in what direction I want to go, will have to wait.

[yuhan0]

Thanks for all your contributions to the Emacs ecosystem! I've already patched it locally so that the cycling commands show all nested branches, along with a fix for #12 (skipping cycle states when the command is a no-op).

I know this is a minor issue compared to other projects like Magit, but if you ever get round to resolving the design and don't mind reviewing a PR, I'd be happy to submit them.

Realistically I work with shallow code outlines (1-3 levels max), so the H+/H* distinction rarely comes up. Those were my only quibbles and easily resolved -- having migrated as a long-time user of the somewhat unwieldy outshine.el, it's been really reliable and a joy to use :)

[tarsius]

With Magit v4.0.0 out the door, I have finally taken a closer look.

That's very nice!

I have made some heavy but essentially cosmetic changes, and pushed the result to main. Thanks for these improvements and your patience.