feat(picker): cache apropos result to speed up

[delphinus]

Description

This is a revised PR from #3399. This makes :Telescope man_pages faster on macOS.

I found man_pages picker is too slow on macOS. This is because the apropos command, that is used in this picker, is much slower on macOS than other UNIX-like systems (Linux, FreeBSD, etc.).

By further investigation, this is derived from SIP (System Integrity Protection) on macOS. apropos uses the DB: /usr/share/man/whatis, but the place is protected on macOS and cannot be written by userland commands. So apropos always scans the whole man directories every time.

How to rebuild the whatis database? whati… - Apple Community

I resolved this by caching the result from apropos. The cache file will be invalidated when man pages are updated. When the system creates, updates, or removes man pages, we can catch events by looking the parent directory's mtime. Directory names to look their mtime are found as below, for example.

• System man pages: /usr/share/man/man1 …… man8
• Homebrew's ones: /opt/homebrew/share/man/man1 …… man8
• Some has also language tags: /opt/homebrew/share/man/ja/man1
• And others listed by manpath command or MANPATH env var.

It also detects MANSECT env var to determine sections shown by apropos. When it detects custom MANSECT, cache filename will change as below. Each cache will be invalidated individually.

• default cache filename: ~/.cache/nvim/telescope-man-pages
• when MANSECT=1,3p,5,n: ~/.cache/nvim/telescope-man-pages-1-3p-5-n

Type of change

Please delete options that are not relevant.

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list relevant details about your configuration

• Run :Telescope man_pages
  • At the first, slow as ever, and faster at next try.
  • It creates the cache: ~/.cache/nvim/telescope-man-pages
• Install a new man page
  • Slow again, but faster at next try.
  • It updates the same cache.

Configuration:

• Neovim version (nvim --version):

  NVIM v0.12.0-dev-2153+g36db6ff2c1-Homebrew
  Build type: Release
  LuaJIT 2.1.1767980792
  Run "nvim -V1 -v" for more info
  

• Operating system and version:

  $ sw_vers
  ProductName:            macOS
  ProductVersion:         26.2
  BuildVersion:           25C56
  

Checklist:

• My code follows the style guidelines of this project (stylua)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (lua annotations)