https://github.com/bfrg/vim-cmake-help
View CMake Documentation inside Vim
https://github.com/bfrg/vim-cmake-help
cmake vim vim-cmake vim-ftplugin vim-plugin vim9script
Last synced: about 1 month ago
JSON representation
View CMake Documentation inside Vim
- Host: GitHub
- URL: https://github.com/bfrg/vim-cmake-help
- Owner: bfrg
- Created: 2019-11-27T14:08:52.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-02-02T22:08:20.000Z (over 1 year ago)
- Last Synced: 2025-03-23T21:22:49.167Z (about 2 months ago)
- Topics: cmake, vim, vim-cmake, vim-ftplugin, vim-plugin, vim9script
- Language: Vim script
- Homepage:
- Size: 43.9 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-vim9 - vim-cmake-help
README
# vim-cmake-help
View [CMake][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][cmake-doc] directly in your browser.
## 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`:
```vim
vim9script
setlocal keywordprg=:CMakeHelpPopup
```
### Mappings
For convenience, the following `` mapping can be used instead of the
commands:
| Mapping | Description |
| -------------------------- | ------------------------------------------------------------------------------- |
| `(cmake-help)` | Open the CMake documentation for the word under the cursor in a preview window. |
| `(cmake-help-popup)` | Open the CMake documentation for the word under the cursor in a popup window. |
| `(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`:
```vim
vim9script
# Open the online CMake documentation for current word in a browser
nmap k (cmake-help-online)
# Open CMake documentation for current word in a preview window
nmap K (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`:
```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:
```vim
vim9script
g:cmakehelp = {
exe: expand('~/.local/bin/cmake'),
browser: 'xdg-open',
maxheight: 20,
scrollup: "\",
scrolldown: "\",
top: "\",
bottom: "\"
}
```
### 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
```bash
$ 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`.
[cmake]: https://cmake.org
[cmake-doc]: https://cmake.org/cmake/help/latest/index.html