How to move the cursor to the next reference, option, heading in man pages?

Question

If we load the built-in man.vim filetype plugin by writing in our vimrc:

runtime ftplugin/man.vim

We can read a man page inside a Vim buffer, using the :Man command described in :h :Man:

MAN                 *ft-man-plugin* *:Man* *man.vim*

Displays a manual page in a nice way.  Also see the user manual
|find-manpage|.

To start using the ":Man" command before any manual page was loaded, source
this script from your startup vimrc file: >

    runtime ftplugin/man.vim

But, similar to this question, when reading a man page, is there a way to move the cursor to the description of the next option, reference and section?

Answer 1

The headers and options are highlighted with syntax highlighting, so your question could be considered as a special case of "how can I jump to the next syntax item?" If we solve that problem, we've also solved this one, since we use it to get to the syntax item for the man page header.

Here's a basic version of such a function:

fun! FindSyntax(name) abort
    " Try to find this syntax item. Unfortunately this can't really be queried
    " with a function, so this is a bit ugly.
    let l:syn_list = execute(':syntax list ' . a:name)
    let l:pattern = ''
    for l:line in split(l:syn_list, '\n')
        if l:line[:len(a:name)-1] == a:name
            let l:pattern = l:line
            break
        endif
    endfor
    if l:pattern == ''
        echoerr 'unable to find syntax pattern for ' . a:name
    endif

    " Find pattern. This is somewhat limited and only works for :syn match ..
    let l:pattern = substitute(l:pattern, a:name . '\s\+xxx match /\(.\+\)/', '\1', 0)[:-3]

    " Jump to next instance of this pattern
    call search(l:pattern)
endfun

It only works stuff defined with :syntax match for now (which is good enough for the purpose of this question), but this can be extended.

You can get the name of the text under the cursor with:

:echo synIDattr(synID(line('.'), col('.'), 1), 'name')

For man pages, this seems to be manSectionHeading and manOptionDesc. We can now use this in various ways:

:call FindSyntax('manSectionHeading')
:call FindSyntax('manOptionDesc')

" Next section
nnoremap <Leader>ns :call FindSyntax('manSectionHeading')<CR>
" Next option
nnoremap <Leader>no :call FindSyntax('manOptionDesc')<CR>

:command NextSection :call FindSyntax('manSectionHeading')
:command NextOption :call FindSyntax('manOptionDesc')

---

I asked a somewhat related question over at Unix.SE last year, by the way: how can I search for bolded or underlined text?, which also has some Vim-specific answers.