bug: Creating the first mark on a line still starts counting marks at "2" for that line, and more count-related weirdness

[miguno]

Did you check docs and existing issues?

• I have read all the trailblazer.nvim docs
• I have searched the existing issues of trailblazer.nvim
• I have searched the exsiting issues of plugins related to this issue

Neovim version (nvim -v)

0.8.2 (release)

Operating system/version

macOS 13.1

Describe the bug

The docs say:

As soon as multiple mark symbols would be displayed in the same line, only the last one will be shown as well as the total number of mark symbols within that line that.

However, I observed the following behavior:

• The total number is always "2" when marking a line for the first time.
• When you create a new mark on a different line, the "2" on the previous mark disappears, and only the new mark shows up with a count of "2".
• When multiple lines are marked once, then only the newest mark retains its (wrong) total number of "2". Navigating through the various marks shows their correct count (count is 1, thus no number is shown); again, with the exception of the very newest mark.
• More information shown in the screenshots below.

Maybe I don't understand yet what should be displayed—maybe some of the behavior is done on purpose. But intuitively it's quite confusing to me. I also wouldn't rule out that there could be some interplay with the rest of my neovim config.

Steps To Reproduce

Open a file that has no marks yet.

Create the first mark. Note how the count is "2" already.

Create another mark some lines down. Its count is already "2", just like for the very first mark a few lines above.

Create yet another mark, again its count is 2.

Now we navigate from the third mark back to the second mark.

We navigate to the very first mark. All marks have a count of 1 displayed now.

Let's navigate forwards again towards the newest, third mark. (We're on the second mark in the following screenshot.)

We're on the newest, third mark again.

Let's create additional marks on the same line. Here's what's displayed after we placed four additional marks on that line (total count is actually 5).

We navigate back to the previous mark. (The fully white block is the current cursor location.) Note the "2->4*" display in the sign column. As shown in the screenshot, which is my trailblazer configuration, "->" is the mark symbol for the current mark, whereas "*" is used for the newest mark.

We navigate back one more mark. We're on mark 3 in the line now. Now it displays "3↷4*", where "↷" is the symbol for the next mark.

We are now on the second mark on that line.

Now we're on the first mark on that line. The sign column says "2↷3*" here.

In this final screenshot we navigated to an earlier mark on a different line (this was the original second mark from the second screenshot in this comment).

Expected Behavior

The total number should match the actual number of marks on a given line. Notably, creating the very first mark on a line should not result in "2" being displayed.

[LeonHeidelbachHHU]

@miguno Some of what you describe is actually the expected behavior of the numbers next to your mark symbols. Maybe my description in the Readme is not precise enough though. Let’s go through what the numbers actually mean.

As you already quoted from the Readme (which might not be clear enough) the numbers are not supposed to count the total number of marks in one line but rather the number of symbols that would be placed in the sign column if the sign column would not be restricted to a maximum of 2 characters. There are 4 possible symbols that can be displayed in the sign column, so the highest possible number that will be shown in the symbol column is 4 if all of the below mark symbols are located on the same line:

1. The „Newest Mark“ symbol
2. The „Current Cursor“ symbol
3. The „Next Mark“ symbol
4. The „Previous Mark“ symbol

As soon as you create a new trail mark it will by default have two of the above symbols, the „Newest Mark“ and the „Current Cursor“ symbol. Whenever you create a new mark after that, the current cursor will automatically jump to it, so it will have the number 2 displayed next to it every time. I think the other situations you described can be derived from this behavior. However, if you don’t like this behavior you can simply disable the mark symbol numbers by setting multiple_mark_symbol_counters_enabled = false in your configuration table.

The only thing that is a bit weird and I cannot seem to reproduce is the behavior where there are two sets of icons and numbers displayed in one line. This might be related to your setup but the numbers and symbols shown follow the correct patterns described above.

[miguno]

Thanks for the detailed explanation. From a user POV, I must confess that the current README is a bit difficult to interpret.

Your explanation above makes sense. That said, just as a piece of feedback for you, the current count behavior is (no pun intended) counter-intuitive to me. Based on your recommendation I just tried with multiple_mark_symbol_counters_enabled = false, and what the plugin shows to me—omitting the counters—is much more intuitive and of course simpler. (Maybe consider making false the default value?)

Additional feedback, related but not directly for this issue:

• I did find the four different mark symbols confusing at first, too, or rather: the existence of 'newest mark' and how it interacts with 'cursor mark' when navigating. Because what's being displayed in the sign column changes the symbol from 'newest' to 'cursor' when the cursor is being navigated to the newest mark line; the effect also means that symbol colors change, too. My initial impression was that the symbols and their colors changed almost randomly. So I wondered, at that point, "Why is there a separate symbol for the newest mark?" See next bullet item. This user confusion can probably also addressed with a better explanation in the README.
• I only played with :TrailBlazerNewTrailMark and :TrailBlazerPeekMovePreviousUp + :TrailBlazerPeekMoveNextDown at first. Because of this, the existence of 'newest mark' didn't make sense because this setup only requires previous/next/cursor symbols. Only later did I discover :TrailBlazerTrackBack, which "consumes" the stack of marks, starting from 'newest'. And its use case is a bit different from the previous feature of new/prev/next with peeking. The confusion described in the previous bullet item can be traced back to this, because as a neovim user I am familiar with standard marks, which are not consumed on use/jump and thus behave like the *Peek* commands of the plugin. Maybe you can find a way to better describe (or display or ...) the two related but different behaviors/use cases? Again, I expected only the new/prev/next behavior, and was tricked by the effects of the back (consume) behavior on the UI.

[LeonHeidelbach]

Thank you for the detailed analysis. That's really helpful. I have to confess, I did not spend as much time thinking about a comprehesive explanation as I did working on the features themeselves. What you described makes a lot of sense though and I will try to incorporate your feedback into the README. The thing is, initially I only wanted to have something like the "Track back" feature, so this was supposed to be the "star of the show" but I probably didn't highlight that well enough. Tracking back allows you to have very short lived marks to jump to if you are in the middle of composing a method and maybe have to quickly look something up and want to return to the same spot where you left off without the actual need of having a persistent mark there. The counters are supposed to aid in understanding what is going to be the next step back or forward if multiple marks are on the same line (i.e. if you don't explicitly have the next and previous symbols visible due to them being on the same line) but I see how this can be confusing if you don't see the intent right away. Maybe it's actually best to have this turned off by default.

[miguno]

The counters are supposed to aid in understanding what is going to be the next step back or forward if multiple marks are on the same line (i.e. if you don't explicitly have the next and previous symbols visible due to them being on the same line)

Well, with multiple marks per line, the visual indicators on the line itself are more than enough to aid with navigation. The sign colum information isn't helpful IMHO, because they can't convey important information such as order of marks (e.g., "If I go to the next mark in this line, to which location in the line will I jump?"; the symbols/counters can't answer this).

Also, in my case, I am much more likely to spread marks across different lines in the same file/buffer or across different files/buffers, than to use multiple marks on the same line. So personally I'd optimize for the former situation, not the latter.

What you described makes a lot of sense though and I will try to incorporate your feedback into the README. The thing is, initially I only wanted to have something like the "Track back" feature, so this was supposed to be the "star of the show" but I probably didn't highlight that well enough.

Thanks, this would be appreciated.

Some suggestions in case it helps:

• Highlight back-tracking as the first and prominent feature in the README. (This probably also sets this plugin apart from others?) Describe 1-2 use cases where back-tracking is super useful. I'd definitely explain the "consume", stack-like behavior here, too. You can even consider explaining how this plugin relates to standard functionality like neovim's tag stack or the jump list, which users are often already familiar with.
• Explain that the plugin also has 'standard' mark/navigation features. What I liked compared to the vanilla behavior is the visual indicators for where the marks are within a line, i.e., not just 'mark = jump to row', but 'mark = jump to row+col).
• Turn off mark counters by default as they are likely confusing at first.

[LeonHeidelbach]

@miguno I will push an update later today, as I'm currently working, and if you have any further suggestions after that I'll be happy to hear about them 👍 .

[miguno]

Thank you, @LeonHeidelbach !

[LeonHeidelbach]

@miguno So I've changed a few things, and added more detailed descriptions. Let me know what you think. 😄

[LeonHeidelbach]

@miguno I will close this issue for now, since the only problem was proper documentation.