fix: man_pages previewer, respecting MANPATH and apropos output parsing (#1764)

- introducing putils writer and use it rather than using PAGER env var
- introducing env for lua/telescope/_.lua job interface
  - to respect MANPATH (and PATH just in case)
- fix for apropos output parsing might return e.g. `alacritty, Alacritty`
  We need to split on first `,`

lua/telescope/_.lua

@@ -299,6 +299,22 @@ M.convert_opts = function(o)
 
   obj.args = args
 
+  if o.env then
+    if type(o.env) ~= "table" then
+      error(debug.traceback "'env' has to be a table")
+    end
+
+    local transform = {}
+    for k, v in pairs(o.env) do
+      if type(k) == "number" then
+        table.insert(transform, v)
+      elseif type(k) == "string" then
+        table.insert(transform, k .. "=" .. tostring(v))
+      end
+    end
+    obj.env = transform
+  end
+
   return command, obj
 end
 

lua/telescope/builtin/internal.lua

@@ -663,6 +663,7 @@ internal.man_pages = function(opts)
     return is_darwin and { "apropos", " " } or { "apropos", "" }
   end)
   opts.entry_maker = opts.entry_maker or make_entry.gen_from_apropos(opts)
+  opts.env = { PATH = vim.env.PATH, MANPATH = vim.env.MANPATH }
 
   pickers.new(opts, {
     prompt_title = "Man",

lua/telescope/finders/async_job_finder.lua

@@ -50,6 +50,7 @@ return function(opts)
       command = job_opts.command,
       args = job_opts.args,
       cwd = job_opts.cwd or opts.cwd,
+      env = job_opts.env or opts.env,
       writer = writer,
 
       stdout = stdout,

lua/telescope/finders/async_oneshot_finder.lua

@@ -11,6 +11,7 @@ return function(opts)
 
   local entry_maker = opts.entry_maker or make_entry.gen_from_string
   local cwd = opts.cwd
+  local env = opts.env
   local fn_command = assert(opts.fn_command, "Must pass `fn_command`")
 
   local results = vim.F.if_nil(opts.results, {})
@@ -47,6 +48,7 @@ return function(opts)
           command = job_opts.command,
           args = job_opts.args,
           cwd = cwd,
+          env = env,
 
           stdout = stdout,
         }

lua/telescope/make_entry.lua

@@ -611,6 +611,11 @@ function make_entry.gen_from_apropos(opts)
 
   return function(line)
     local keyword, cmd, section, desc = line:match "^((.-)%s*%(([^)]+)%).-)%s+%-%s+(.*)$"
+    -- apropos might return alternatives for the cmd which are split on `,` and breaks everything else
+    -- for example on void linux it will return `alacritty, Alacritty` which will later result in
+    -- `man 1 alacritty, Alacritty`. So we just take the first one.
+    -- doing this outside of regex because of obvious reasons
+    cmd = vim.split(cmd, ",")[1]
     return keyword
         and sections[section]
         and {

lua/telescope/previewers/buffer_previewer.lua

@@ -610,7 +610,7 @@ end, {})
 
 previewers.man = defaulter(function(opts)
   local pager = utils.get_lazy_default(opts.PAGER, function()
-    return vim.fn.executable "col" == 1 and "col -bx" or ""
+    return vim.fn.executable "col" == 1 and { "col", "-bx" } or { "cat" }
   end)
   return previewers.new_buffer_previewer {
     title = "Man Preview",
@@ -620,8 +620,9 @@ previewers.man = defaulter(function(opts)
 
     define_preview = function(self, entry, status)
       local win_width = vim.api.nvim_win_get_width(self.state.winid)
-      putils.job_maker({ "man", entry.section, entry.value }, self.state.bufnr, {
-        env = { ["PAGER"] = pager, ["MANWIDTH"] = win_width },
+      putils.job_maker(vim.deepcopy(pager), self.state.bufnr, {
+        writer = { "man", entry.section, entry.value },
+        env = { ["MANWIDTH"] = win_width, PATH = vim.env.PATH, MANPATH = vim.env.MANPATH },
         value = entry.value .. "/" .. entry.section,
         bufname = self.state.bufname,
       })

lua/telescope/previewers/utils.lua

@@ -33,12 +33,25 @@ utils.job_maker = function(cmd, bufnr, opts)
   -- if any of them are missing, cache will be skipped
   if opts.bufname ~= opts.value or not opts.bufname or not opts.value then
     local command = table.remove(cmd, 1)
+    local writer = (function()
+      if opts.writer ~= nil then
+        local wcommand = table.remove(opts.writer, 1)
+        return Job:new {
+          command = wcommand,
+          args = opts.writer,
+          env = opts.env,
+          cwd = opts.cwd,
+        }
+      end
+    end)()
+
     Job
       :new({
         command = command,
         args = cmd,
         env = opts.env,
         cwd = opts.cwd,
+        writer = writer,
         on_exit = vim.schedule_wrap(function(j)
           if not vim.api.nvim_buf_is_valid(bufnr) then
             return