What does man -k . output look like on your platform? Is it fast?

[dseomn]

Background: The :Man command currently completes its args as commands instead of manpages:

vim/runtime/ftplugin/man.vim

Line 63 in a95085e

com -nargs=+ -complete=shellcmd Man call dist#man#GetPage(<q-mods>, <f-args>)

I'm about to start working on a PR to use the command man -k . to get a list of actual manpages for :Man completion, but https://pubs.opengroup.org/onlinepubs/9799919799/utilities/man.html is very underspecified about the format that command will output.

On Debian testing, I get output that looks like this:

List::UtilsBy (3pm)  - higher-order list utility functions

On FreeBSD 14.2, it looks a bit different, with multiple manpages per line sometimes (I think):

ar, ranlib(1) - manage archives

If man -k . outputs a different format on your computer and you want to help me parse that for :Man completion, please share examples of what that format looks like.

Additionally, time man -k . > /dev/null shows 0m0,086s real time on my Debian desktop which is fast enough that I don't think it's worth caching results. If it's significantly slower for you, please let me know that too.

[dseomn]

macos has some interesting differences. Notably, (section) can appear multiple times so looking for the first instance only is wrong, it looks like () can appear in the page name itself, and parentheses can appear in the description after the dash:

BacklightdTester(1), Other_name_for_same_program()(1), Yet another name for the same program.(1) - This line parsed for whatis database
cron(8)                                    - daemon to execute scheduled commands (Vixie Cron)

[zzzyxwvut]

Why not complete with -complete=file_in_path?

Just a proof of concept:

diff --git a/runtime/autoload/dist/man.vim b/runtime/autoload/dist/man.vim
index 281b75158..91396747b 100644
--- a/runtime/autoload/dist/man.vim
+++ b/runtime/autoload/dist/man.vim
@@ -117,8 +117,9 @@ func dist#man#GetPage(cmdmods, ...)
     let sect = a:1
     let page = a:2
   elseif a:0 >= 1
-    let sect = ""
-    let page = a:1
+    let file = split(a:1, '\.')
+    let sect = get(file, 1, '')
+    let page = get(file, 0, a:1)
   else
     return
   endif
diff --git a/runtime/ftplugin/man.vim b/runtime/ftplugin/man.vim
index 45c2bb239..309a1993b 100644
--- a/runtime/ftplugin/man.vim
+++ b/runtime/ftplugin/man.vim
@@ -60,7 +60,8 @@ if &filetype == "man"
 endif
 
 if exists(":Man") != 2
-  com -nargs=+ -complete=shellcmd Man call dist#man#GetPage(<q-mods>, <f-args>)
+  let &path = join(map(range(1, 8), '"/usr/share/man/man" . v:val'), ',') . ',' . substitute($MANPATH, ':', ',', 'g')
+  com -nargs=+ -complete=file_in_path Man call dist#man#GetPage(<q-mods>, <f-args>)
   nnoremap <Leader>K :call dist#man#PreGetPage(0)<CR>
   nnoremap <Plug>ManPreGetPage :call dist#man#PreGetPage(0)<CR>
 endif

[dseomn]

Despite the name, runtime/ftplugin/man.vim is meant to be used from anywhere, not just ft=man buffers:

vim/runtime/ftplugin/man.vim

Lines 10 to 11 in 62e8228

	" To make the ":Man" command available before editing a manual page, source
	" this script from your startup vimrc file.

So I don't think setting 'path' there is a good idea. Looking at files would still be possible, but I think using man -k is easier on systems that support it, for a few reasons:

$MANPATH doesn't look as easy to use as it seems. Both man-db and mandoc seem to have ways to configure the path other than the environment variable. With man-db, it looks like manpath can print the actual path. With mandoc, it looks like man -w does that. Dunno about other systems.

On my Debian system, the search within the path isn't as simple as man{1..9}, because of language directories like /usr/share/man/nl. That could be handled too, it's just one extra step.

Also on my system, manpages seem to be compressed, like /usr/share/man/man1/bash.1.gz. So that's another extra step to strip it, and to do it correctly for new compression extensions in the future. Is man7/foo.7.7z the manpage for foo in section 7 compressed with 7z, or the uncompressed manpage for foo.7 in section 7z? I'm sure it could be handled, but I'd rather not try to parse that.

[dseomn]

NetBSD doesn't seem to list all manpages with man -k .

Between that and the other differences between platforms, I'm leaning towards using uname to guess which man implementation is available, and adding a configuration knob for users to override that guess. Then I'll implement completion that works with man-db, and default to the current behavior for other man implementations. If others want to add better manpage completion for other man implementations, they can do that.

[benknoble]

Some timing on Apple systems with hyperfine --warmup=10 --output=/dev/null:

• Old no-longer supported hardware running 12.7.6:

  Benchmark 1: man -k .
    Time (mean ± σ):     385.4 ms ±   2.1 ms    [User: 115.4 ms, System: 283.5 ms]
    Range (min … max):   382.8 ms … 389.2 ms    10 runs
  

• New hardware running 14.7.3 and whatever monitors corporate IT has installed:

  Benchmark 1: man -k .
    Time (mean ± σ):     7.243 s ±  0.205 s     [User: 1.115s, System: 3.811s]
    Range (min … max):   7.011 s …  7.594 s     10 runs
  

Yikes! That would be unusable on the second system without caching.

[dseomn]

Wow, that's much slower than I expected, to the point that it wouldn't be great even with caching. If anybody wants to implement this on mac*, hopefully there's some other way to do it, like maybe looking at the files suggested in #16794 (comment).

* I ended up giving up on a portable solution, and only implemented this for man-db in #16843, but maybe some of that code could be factored out and reused for other man implementations.

P.S. I think you responded to my recent patch on the git mailing list too? Hello again, and small world :)

[benknoble]

I try to keep up with Git and Vim where I know what's going on, yep!