Skip to content

View CMake Documentation inside Vim

Notifications You must be signed in to change notification settings

bfrg/vim-cmake-help

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

43 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

vim-cmake-help

View CMake documentation inside Vim (>= 8.2.4980).

The plugin provides three methods for quickly displaying CMake documentation:

  1. Open the documentation in a new split window.
  2. Open the documentation in a popup window at the current cursor position (or mouse pointer).
  3. Open the CMake Reference Documentation directly in your browser.

out

Usage

Commands

Command Description
:CMakeHelp {arg} Open the CMake documentation for {arg} in a preview window.
:CMakeHelpPopup {arg} Open the CMake documentation for {arg} in a popup window.
:CMakeHelpOnline [{arg}] Open the online CMake documentation for {arg} in a browser.

{arg} can be any standard CMake keyword. Use TAB in command-line mode for argument completion and to get a list of supported keywords.

Example

To open the CMake documentation for the word under the cursor in a popup window with K, add the following to ~/.vim/after/ftplugin/cmake.vim:

vim9script
setlocal keywordprg=:CMakeHelpPopup

Mappings

For convenience, the following <plug> mapping can be used instead of the commands:

Mapping Description
<plug>(cmake-help) Open the CMake documentation for the word under the cursor in a preview window.
<plug>(cmake-help-popup) Open the CMake documentation for the word under the cursor in a popup window.
<plug>(cmake-help-online) Open the online CMake documentation for the word under the cursor in a browser.

Example

Add the following to ~/.vim/after/ftplugin/cmake.vim:

vim9script

# Open the online CMake documentation for current word in a browser
nmap <buffer> <leader>k <plug>(cmake-help-online)

# Open CMake documentation for current word in a preview window
nmap <buffer> <leader>K <plug>(cmake-help)

Popup window

If the documentation doesn't fit into the popup window, a scrollbar will appear on the right side. The popup window can then be scrolled with S-PageUp and S-PageDown, or alternatively, using the mouse wheel. Pressing CTRL-C or moving the cursor in any direction will close the popup window.

The keys for scrolling the popup window are configurable.

Mouse hovers

The plugin provides a balloonexpr that will open the CMake documentation for the word under the mouse pointer in a popup window. To enable this feature, add the following to ~/.vim/after/ftplugin/cmake.vim:

vim9script

import autoload 'cmakehelp.vim'

setlocal ballooneval
setlocal balloonevalterm
setlocal balloonexpr=cmakehelp.Balloonexpr()

Moving the mouse pointer outside the current word closes the popup window.

Configuration

g:cmakehelp and b:cmakehelp

Options can be set either through the buffer-local variable b:cmakehelp (specified for cmake filetypes), or the global variable g:cmakehelp. The variable must be a dictionary containing any of the following entries:

Key Description Default
exe Path to cmake executable. value found in $PATH
browser Browser executable. firefox
scrollup Key for scrolling the text up in the popup window. S-PageUp
scrolldown Key for scrolling the text down in the popup window. S-PageDown
maxheight Maximum height for popup window. Set to 0 for maximum available. 0
top Key for jumping to the top of the buffer in the popup window. S-Home
bottom Key for jumping to the botton of the buffer in the popup window. S-End

Example:

vim9script

g:cmakehelp = {
    exe: expand('~/.local/bin/cmake'),
    browser: 'xdg-open',
    maxheight: 20,
    scrollup: "\<c-k>",
    scrolldown: "\<c-j>",
    top: "\<c-t>",
    bottom: "\<c-g>"
}

Popup highlightings

The appearance of the popup window can be configured through the following highlight groups:

Highlight group Description Default
CMakeHelp Popup window background and normal text. Pmenu
CMakeHelpScrollbar Scrollbar of popup window. PmenuSbar
CMakeHelpThumb Thumb of scrollbar. PmenuThumb

Installation

$ cd ~/.vim/pack/git-plugins/start
$ git clone https://github.com/bfrg/vim-cmake-help
$ vim -u NONE -c 'helptags vim-cmake-help/doc | quit'

Note: The directory name git-plugins is arbitrary, you can pick any other name. For more details see :help packages. Alternatively, use your favorite plugin manager.

License

Distributed under the same terms as Vim itself. See :help license.

Releases

No releases published

Packages

No packages published