feat(extra): add manpages picker

[Dook97]

Related: #2209 #2208

A manpages picker.

532095391-32866873-d91e-43a7-9aea-8ab6e42721e7.mp4

@echasnovski Submitting as a PR for your consideration whether this is a good
fit for mini.extra. Together with @drowning-cat I think we've made the code
better and more compact. If it is your call that this shouldn't be included
I'll alter the code in #2209 for it to be a custom picker and be done with it −
I've already spent way too much time on this 😅

• I have read CONTRIBUTING.md
• I have read CODE_OF_CONDUCT.md

[drowning-cat]

I like your passion. I won't be afraid to say that we like your passion, though I'll speak from my own perspective. Not only do the man pages themselves feel kind of rough in Neovim, especially with their behavior as described in the Show and Tell discussion, but they are also an OS dependent, so the picker may need to be handled and documented differently.

There are also many minor things to think about, such as what to do with hard or soft wrapping, or whether manpages should be opened like help pages by reusing the same window. In general, mini.nvim prefers a slow and steady approach, so I think it's better to wait for this feature, like a good wine, starting with the documentation. Though echasnovski and mini.nvim team may have a different opinion from mine, so let's wait for their response.

[Dook97]

Sorry if I'm being too impatient. I want to free up some mental bandwidth so that I can actually do some work with my editor, instead of working on it - I'm not great at multitasking 😅 But if the project has a more conservative policy, that's obviously fine.

Thanks for all the help making the picker better.

[echasnovski]

Thanks for the PR!

All right, I think it might indeed be a reasonable addition to 'mini.extra'. Probably not in its current form, as it still looks a bit complex. In particular, I am not very fond of an additional "scope" option and rather cryptic handling of everything man related.

I'd have to investigate about the best approach here.

---

I like your passion. I won't be afraid to say that we like your passion, though I'll speak from my own perspective.

Thanks for the positive attitude! I'd also like to clarify: speaking on behalf of the MINI team preferably should be reserved for the team itself. Doing otherwise might create unintended impressions.

[Dook97]

I am not very fond of an additional "scope" option

The added complexity seemed to me small enough that having it was better than not, but if you disagree I don't mind removing it. Personally I won't be using the option anyway.

[echasnovski]

I want to defend myself here. I don't see myself as part of the team, a member, a future member, or even closely related to the project. I shared my opinion because I tried rewriting the picker to suit my own taste and liked the idea in general. "We" was not meant to represent the project; it was simply my assumption that you appreciate when people share or contribute to the project.

Sorry, didn't at all mean to make you feel like having to defend yourself. Your contributions to discussions have been very valuable. And you are of course correct that I appreciate seeing people share and/or contribute to MINI.

It might be a result of my personal pet peeve about people using too broad "we" when a more narrow "I" is enough.

---

The added complexity seemed to me small enough that having it was better than not, but if you disagree I don't mind removing it. Personally I won't be using the option anyway.

@Dook97, it is not only about the local options, but overall code. Like having to go the MiniPick.builtin.help path of custom mappings or rather cryptic item:match("^((.-)%s*%(([^)]+)%).-)%s+%-%s+(.*)$") and string.format("silent re! 2>&- MANWIDTH=%s man %s %s", width, section, cmd).

I'll be looking into this myself, as this will also require testing and documentation. So you can "free up some mental bandwidth" :)

[Dook97]

FYI the regex is stolen from telescope's implementation.

I'll be looking into this myself, as this will also require testing and documentation. So you can "free up some mental bandwidth" :)

Much appreciated 😅

[drowning-cat]

(hide if needed)

Name

After some initial research, I can say that the complexity of the query is justified. However, the query provided by Telescope needs to be reworked, as it does not discard the /arch part described below, and we also don't actually need the description to be parsed.

There are two main man page viewers: man-db (used in Arch Linux, Ubuntu, Fedora, ...) and mandoc (used in MacOS, Void Linux, Alpine Linux, BSD, ...). Switching between them on Arch Linux and reindexing actually changes how man -k . displays entries.

man-db produces a predictable format:

alacritty (1)           - A fast, cross-platform, OpenGL terminal emulator.
alacritty (5)           - TOML configuration file format.
alacritty-bindings (5)  - Default configuration file bindings.
alacritty-msg (1)       - Send messages to Alacritty.

On the other hand, mandoc can display results in various forms:

Alacritty example

alacritty, Alacritty(1) - A fast, cross-platform, OpenGL terminal emulator.
alacritty-msg(1) - Send messages to Alacritty.
alacritty, Alacritty(5) - TOML configuration file format.
alacritty-bindings(5) - Default configuration file bindings.

Void Linux search:

abidb(1)
afterstep_faq(1, 1x)
alacritty, Alacritty(1)

OpenBSD search:

amd64_iopl(2/amd64)
a64l, l64a(3)

From Void Linux apropos man page for mandoc (see https://man.voidlinux.org/apropos.1):

Each output line is formatted as

name[, name...](sec) - description

Where “name” is the manual's name, “sec” is the manual section, and “description” is a short summary.
If an architecture is specified, it’s displayed as

name(sec/arch) - description

Entries are separated by a comma followed by a space , , but I did not find any entries that use a comma in their names, so using just comma , should be fine.

There might be errors in the output (Void Linux):

In rare cases, strange entries may appear (Void Linux search):

acl_extended_file_nofollow, acl_extended_file, acl_extended_file,(3)
tpm2_clearcontrol, tpm2_clearcontrol(1)(1)

Width

Seems like mandoc does not support the MANWIDTH env variable:

# man-db
MANWIDTH=100 man 1 tmux

# mandoc
man -O width=100 1 tmux

[Dook97]

we also don't actually need the description.

I find it useful. You might not know exactly the manpage you're looking for and the description can contain keywords by which it may be found.

Seems like mandoc does not support the MANWIDTH env variable:

It would be optimal if we could just use the Man plugin instead of running external commands. That's the way telescope does it too, but it seems to clash with something about how mini.pick handles things 🤷

[echasnovski]

After some initial research, I can say that the complexity of the query is justified.
...
Seems like mandoc does not support the MANWIDTH env variable:

Thanks, both of these are helpful. The different format can be addressed on a case-by-case basis.

I have a solution that looks reasonable. It should handle commas and needs one character change to handle abidb(1) (no space). Not sure if amd64_iopl(2/amd64) needs special handling. Won't man 2/amd64 amd64_iopl work in this case?

It would be optimal if we could just use the Man plugin instead of running external commands. That's the way telescope does it too, but it seems to clash with something about how mini.pick handles things 🤷

It can be made to work with :Man, but it is visibly slow and opens listed buffer for each manpage (which has unwanted side effects). So I think settling on solution that doesn't rely on it at all is better.

[drowning-cat]

Won't man 2/amd64 amd64_iopl work in this case?

I tried it on an online virtual machine. It printed an error and also opened the man page (I think as a fallback).

P.S. I don't have man pages with the /arch suffix to test this on my machine (Arch Linux).

[echasnovski]

I tried it on an online virtual machine. It printed an error and also opened the man page (I think as a fallback).

That will be super helpful. Thanks!