search

ggandor / flit.nvim

Enhanced f/t motions for Leap
The Unlicense
364 stars 15 forks source link

[Feature request] Documentation #9

Open gsinclair opened 1 year ago

gsinclair commented 1 year ago

I am just getting started with leap and flit, and I don't quite understand what flit does that leap doesn't do.

OK, as I wrote that sentence, I realised that with flit you use one search character, not two. It would be good for that – and other things – to be written in the README, and for an official "help" document to exist.

I also don't actually know how to complete the search in flit and get back to normal editing.

ggandor commented 1 year ago

I don't quite understand what flit does that leap doesn't do

I guess "f/F/t/T motions" is pretty obvious, isn't it?

I also don't actually know how to complete the search in flit and get back to normal editing.

The exact same way as in Leap (esc or entering a label, or pressing any non-label key and continuing editing).

briandipalma commented 1 year ago

The exact same way as in Leap (esc or entering a label, or pressing any non-label key and continuing editing).

Locally I'm not seeing that. I've attached a screen recording of what I see.

Firstly I press f then : then the f label and then...leap/flit seem to sit there waiting for more input...I have to hit Esc to get to where I want. What am I missing here? Is it the fact I had groups visible? I don't see how that matters TBH, I pressed f, I made my choice...

https://user-images.githubusercontent.com/1597820/222487708-d9534e20-b1c3-4e6a-b51f-e00b2172cb91.mp4

briandipalma commented 1 year ago

The other thing I notice is that with leap I can press Tab and it has the same effect as Esc but in flit it seems to just jump back instead...

briandipalma commented 1 year ago

Oh I'm using LazyVim if that makes any difference: https://github.com/LazyVim/LazyVim/blob/main/lua/lazyvim/plugins/editor.lua#L175

ggandor commented 1 year ago

@briandipalma You can move forward by repeatedly pressing f (or t for a t invocation), like clever-f does. "f" over the first target is just a "virtual" label in this case, under the hood f initiates traversal mode (that is why Tab reverts the jump). So to be clear, the first label will be replaced by whatever you've set as the trigger key in flit's setup, it is not the first label from the usual label set (leap.opts.safe_labels), and is not handled internally as an actual label, different code is executed.

If you select any other label, that works as usual, exiting flit.

briandipalma commented 1 year ago

So to select the first match and exit flit I can use either Esc or Tab for the second match I must hit the search trigger key a second time (f or t) then the Esc key for every other match I just need to type the label?

I'll throw a few sentences together tomorrow for the README along with a note on navigating groups and traversal mode as I think that might be helpful for users/casual browsers.

briandipalma commented 1 year ago

@gsinclair https://github.com/ggandor/flit.nvim/pull/26 to close this issue? I don't know if there's much else needed to talk about apart from maybe groups. I feel they are covered in leap OK already.

ggandor commented 1 year ago

So to select the first match and exit flit I can use either Esc or Tab for the second match I must hit the search trigger key a second time (f or t) then the Esc key for every other match I just need to type the label?

You don't need to esc. That is why there is a safe_labels list for Leap (Flit uses only that, and not the extended labels list). If you press any key that is not a label, it will be fed forward to Neovim. If you press e.g. l, it exits flit and the cursor will be moved to the right.

https://github.com/ggandor/leap.nvim/blob/de9c1b3c694078baf4e9be4288dbcff10a74a9f2/doc/leap.txt#L178-L186

https://github.com/ggandor/flit.nvim/pull/26 to close this issue?

There is no need to duplicate the documentation. Flit is Leap. It is a leap call under the hood, with special targets (1-char patterns instead of 2-char patterns). Everything works exactly the same way - the only extra thing is that f/F and t/T will be added as next_target/prev_target special keys, so you can traverse in the "clever-f" way. https://github.com/ggandor/flit.nvim/issues/19#issuecomment-1418941230

briandipalma commented 1 year ago

There are multiple people raising issues because they are confused about how flit works, you just linked to another issue raised by someone else. The video in the README isn't enough without some explanation. Duplicating a few sentences might reduce that confusion and increase the number of people who use flit.

FWIW I've never heard of "clever-f" before this thread.

ggandor commented 1 year ago

Still, there's no point in copying the "usage" sections of Leap in a condensed form. No Telescope extension starts by explaining how to use and configure Telescope. The "clever-f" behavior could be explained in a sentence or two though, I agree, that is the specialty here.

FWIW I've never heard of "clever-f" before this thread.

It's linked right under "Features".