search

orbitalquark / textadept

Textadept is a fast, minimalist, and remarkably extensible cross-platform text editor for programmers.
https://orbitalquark.github.io/textadept
MIT License
624 stars 38 forks source link

Feature Request: Help in curses mode should show md files #540

Closed HGpunktT closed 3 weeks ago

HGpunktT commented 1 month ago

When in curses mode and in a graphical terminal, Help calls a webbrowser to display manual.html or some other HTML file, if available. In case the HTML files are not available or no webbrowser is installed, quietly nothing is shown. My suggestion is to open the appropriate md file (say docs/manual.md) in a new buffer. So even a Linux user on a system without a GUI can use textadept and get help when needed and textadept does not rely on an external program.

orbitalquark commented 4 weeks ago

I see where you are coming from, however a vast majority of users are downloading and using the prebuilt archives with HTML source, so they would not run into this issue unless they are in a non-GUI terminal environment.

I feel like this request would really only help in a non-graphical environment on Linux, and even then there are two pain points:

  1. How to reliably detect a non-graphical environment (without false-positives).
  2. How to detect that xdg-open errored out in a reasonable amount of time without blocking the application.

The difficulty surrounding point 2 is that os.spawn() will not return an error since xdg-open exists, os.spawn():wait() will block Textadept until the command exists with a (potentially non-zero) exit code, and timeout() is not implemented in the terminal version to check for process exit shortly after spawn. I could use a process exit callback and open the markdown help for non-zero status, but if xdg-open succeeds while the application itself closes with non-zero status after showing help, then Textadept could unexpectedly (to the user) open the markdown help.

Linux users in a non-GUI environment could could simply add to their ~/.textadept/init.lua:

textadept.menu.menubar['Help/Show Manual'][2] = function() io.open_file(_HOME .. '/docs/manual.md') end
textadept.menu.menubar['Help/Show LuaDoc'][2] = function() io.open_file(_HOME .. '/docs/api.md') end

I just don't see a clean way to handle this request in a cross-platform, cross-UI way. This is one of those quality-of-life improvements where the amount of effort for such a small subset of users doesn't seem worth it. I feel like users that take the time and understand how to compile the application from source can easily workaround the lack of HTML documentation if needed.

Thanks for bringing this up though.

HGpunktT commented 4 weeks ago

There can be a very simple solution, but I doubt whether that would please other users: When requesting Help, textadept-curses always opens the md files in a new buffer textadept-gtk always opens the HTML files in a webbrowser Maybe when there are only a few users of textadept-curses that would have little impact!?

orbitalquark commented 4 weeks ago

I prefer to keep the current behavior, as I use it in both the GUI and terminal versions. Users who do not have (or do not want) help to open in a web browser can use what I suggested to modify their help menu commands.

HGpunktT commented 3 weeks ago

To achieve the desired behaviour, I modified ~/.textadept/init.lua following your suggestion: if CURSES then textadept.menu.menubar['Help/Show Manual'][2] = function() io.open_file('/usr/share/textadept/docs/manual.md') end textadept.menu.menubar['Help/Show LuaDoc'][2] = function() io.open_file('/usr/share/textadept/docs/api.md') end end