[mini.extra] a manpages picker

[Dook97]

Related: #2208

I wrote a manpages picker for mini.pick. Here it is in action:

out.mp4

Code:

--- Man pages picker
---
--- Pick from system manpages.
---
---@param local_opts __extra_pickers_local_opts
---   Possible fields:
---   - <scope> `(string)` - one of "all" (all man sections) or section string.
---     Default: "all".
---@param opts __extra_pickers_opts
MiniExtra.pickers.man = function(local_opts, opts)
  local pick = H.validate_pick("man")
  local_opts = vim.tbl_deep_extend("force", { scope = "all" }, local_opts or {})

  local load_man = function(item)
    local keyword, cmd, section, desc = item:match("^((.-)%s*%(([^)]+)%).-)%s+%-%s+(.*)$")
    local width = vim.api.nvim_win_get_width(0)
    cmd = vim.split(cmd, ",")[1]
    vim.cmd(string.format("silent re! 2>&- MANWIDTH=%s man %s %s", width, section, cmd))
    vim.cmd("Man!")
    vim.cmd("norm gg0")
  end

  local choose = function(item, splitmode)
    vim.cmd(splitmode or "new")
    load_man(item)
    local win = vim.api.nvim_get_current_win()
    vim.schedule(function() vim.api.nvim_set_current_win(win) end)
  end

  local preview = function(buf_id, item)
    vim.api.nvim_buf_call(buf_id, function() load_man(item) end)
  end

  local map_custom = function(char, splitmode)
    local f = function()
      choose(pick.get_picker_matches().current, splitmode)
      return true
    end
    return { char = char, func = f }
  end

  local conf_maps = pick.config.mappings
  local mappings = {
    choose_in_split   = "", show_man_in_split   = map_custom(conf_maps.choose_in_split, "new"),
    choose_in_vsplit  = "", show_man_in_vsplit  = map_custom(conf_maps.choose_in_vsplit, "vnew"),
    choose_in_tabpage = "", show_man_in_tabpage = map_custom(conf_maps.choose_in_tabpage, "tabnew"),
  }

  local cmd = { "man", "-kls", local_opts.scope == "all" and "" or local_opts.scope, "" }
  local source = { name = "Manpages", choose = choose, preview = preview }
  opts = vim.tbl_deep_extend("force", { source = source, mappings = mappings }, opts or {})
  return pick.builtin.cli({ command = cmd }, opts)
end

It is currently written as a builtin picker, which was made clear in #2208 that it won't be. If it is decided, that it would be accepted into mini.extra, I would rewrite it for that purpouse. Rewritten as mini.extra picker. That wasn't hard at all lol.

[drowning-cat]

I like the idea, thanks for sharing. Is there a reason not to use MiniPick.builtin.cli in this case?

[Dook97]

Frankly I'm not well oriented in mini's APIs. I'll look into it tomorrow.

[Dook97]

Thanks for the suggestion. Edited in the main post.

[echasnovski]

Thanks for sharing!

My first suggestion would be to indeed try to follow the advice from this comment and see how much MiniPick.builtin.cli() can simplify the code. It would certainly not need an io.popen() approach.

[Dook97]

Thanks for the suggestion. Edited in the main post.

[drowning-cat]

I ran into so many problems with man pages while trying to rewrite your code using the :Man command directly:

1. Man pages are not restored between sessions, even though the window keeps its name. Does work as expected from time to time.
2. Opening a man page in a small window prints escape sequences and occasionally produces errors.
3. Using :hide Man {page} {name} reuses an existing buffer with all the artifacts and the same wrapping (vim.g.man_hardwrap = 1 by default), even if the buffer is empty (see p.1). Soft wrapping doesn’t really help because of p.2, and some pages look bad anyway (for example, Tcl).

So, running man as an external command makes sense to me.

Other:

• Man pages are very slow to open, especially large ones like tmux (which is relevant for the preview).
• Personally, I would use man -k, since it is easier for me to understand.

[drowning-cat]

There is also an additional problem, default conceal:

To prevent this, use man -l -k . or apropos -l -k .

[Dook97]

So, running man as an external command makes sense to me.

Yep, I tried using the Man plugin directly too and came to the same conclusion.

slow

Even extremely large manpages like gcc's open in less than half a second for me. I don't know what's causing the issue for you. Have you tried comparing just regular man tmux and the picker preview?

session

Yes, you're right that does appear to be broken. I'll try fiddling with sessionopts, see if that fixes it.

I edited the function to use man -k and the -l option. Thanks for spotting that.

[Dook97]

The issue of Man buffers not being preserved on session load seems to be orthogonal to the picker. Maybe worth reporting to upstream.

[drowning-cat]

I agree that it could be a feature request, but I'm hesitant to create an issue myself for now without taking a closer look.

[echasnovski]

I'll close this in favor of #2212.