feat: Add spawn vim docs

[deepanchal]

Description

This PR adds how-to-spawn-vim documentation under Recipes > Applications > Spawn External Editor (Vim)

I am now using hello-world-template as base for my example to keep things simple (https://github.com/ratatui-org/ratatui-website/pull/651/commits/31fc71c8d3fa99dd182871c47f6ea14c35617f45) and I have added logic to spawn vim in a separate commit (https://github.com/ratatui-org/ratatui-website/pull/651/commits/8380d5b4185879745350cc1d613d70acbc91e81f).

I am not familiar with astro but I tried to use other examples as reference to write this documentation. Please let me know if I missed anything. Thanks!!

Related Issue

Ref #406

Images

[joshka]

This seems overly specific to the component template and has a lot of code just to show off the vim part. I have a few concerns with this:

• we have to maintain that code - this is likely to get stale fast
• the specific problem and solution are obscured by everything else that is part of the application (actions, events, keys, etc.)
• people unfamiliar with the component template have to learn how that works just to understand the recipe
• The tui module setup code likely will go away at some point as it gets replaced by stuff from https://github.com/ratatui-org/ratatui/pull/1180 or https://github.com/ratatui-org/ratatui/pull/280 (or whatever we settle on)
• What the problem is and how the solution solves it isn't all that clear

If you were able to simplify this to an app that just showed off the problem and solution, this would be much clearer. The problem are:

• applications read events, either synchronously, in another thread, or in an async task via the event stream
• applications manage the terminal state, such as raw mode, alternate screen, mouse capture etc.

The solution really needs to show off how to:

• before spawning processes suspend / stop any event reading
• restore the terminal state up that whatever your sub process needs to work properly
• reset these after the sub process finishes
• any abstractions like the component template on top of the plain crossterm stuff should probably be omitted (or perhaps noted for follow up with a some small snippets)

This likely should also have a bit of discussion about termion at the end that shows how to access the backend to do this (requires an unstable flag to get at the backend_mut function and call the suspend functions)

This is just my opinion - I know you've been working on this with @kdheepak who knows a lot more about this template than I do, so I'd let him chime in about whether this is worth keeping in this form or simplifying.

[deepanchal]

Thanks for the feedback! As I was writing this, I also noticed that there's quite a lot of boilerplate coming from component template. I was in the process of removing excess code from this template. I totally agree with your key points on clear problem and solution. I will address those points and make it more cleaner. Also, I am not familiar with writing documentation so I am sure that the wording in the documentation can be improved. I will try to improve docs as well. I will wait for @kdheepak's opinion before I make any big changes in the PR.

[kdheepak]

I agree with your comments. It should be a lot simpler to discuss just the aspect of starting an external process like vim.

One thing I wanted to note is that when I've attempted to do do this without the pattern used in the component template, it resulted in issues where ANSI RGB values would be printed into the TUI on returning back from vim.

See for example this commit from @orhun where he made a change to ensure it worked correctly: https://github.com/orhun/rattler-build/commit/84ea16a4f5af33e2703b6330fcb977065263cef6

I first saw this issue in https://github.com/kdheepak/taskwarrior-tui/issues/46 The reason this occurred is because when vim wants to find out the background color of the terminal, and the response to that request is written to stdin.

When this issue occurs, the response is written to stdin which is read by crossterm as if a user is typing it and that is sent to the keyevents and that ends up getting processed by the TUI.

I know that the combination of using select! + cancellation_token + tokio the way it is used in the component template does not cause this issue. But I haven't tested other ways to narrow down exactly what causes it and what doesn't cause it.

This issue is particularly annoying because it is not always reproducible. I never noticed it on iTerm until I decreased the tick time when using tokio. I noticed it happened more when I was using a background thread to send events to the main thread and was not able to solve it when using a AtomicBool as a Mutex lock to pause the background thread.

Currently, I don't know why the other methods didn't work, and I definitely didn't comprehensively test everything. I was changing multiple things at the same time when I was testing this in taskwarrior-tui and landed on a solution with tokio, select! and cancellation_tokens that worked.

I would like to ensure that this RGB issue doesn't occur with whatever recipe is posted on ratatui.rs because if it does we'll get a lot of questions about what is going on for users that copy paste the code.

[kdheepak]

Thanks for sharing a PR and describing your steps to solve this problem here and on discourse! Even just this information will be useful for those that try to do the same thing and come across this!

[deepanchal]

@joshka @kdheepak I have force pushed to this branch with a much simpler example using hello-world template and updated the docs accordingly. I just had a few questions

• I feel that I am not explaining the process clearly in Handle Events section. Is the template too simple that it doesn't address the problems and solutions mentioned in https://github.com/ratatui-org/ratatui-website/pull/651#issuecomment-2199157733
• Does this example need vhs gif to demonstrate how it works?
• I have added a tip to use edit crate for opening editor at the very bottom. Should this be moved to Handle Events section?
• Should I include my original diff from this pr comment https://github.com/ratatui-org/ratatui-website/issues/406#issuecomment-2198699195 as a tip in this doc?

If any of you can review these new changes whenever you get a chance, that will be helpful! Thanks!!