hiphish / info.vim Goto Github PK

Browse info files from Vim (mirror)

Home Page: https://gitlab.com/HiPhish/info.vim

License: MIT License

Shell 2.61% Vim Script 96.78% Makefile 0.60%

info.vim's Introduction

Info.vim: Read and navigate Info files in Vim

Info.vim provides two features: syntax highlighting for Info files generated from Texinfo, and it implements a reader for browsing and navigating through Info files installed on the user's system.

Info is the file format of the info command-line program and Emacs's Info-mode. This format is most often generated from Texinfo source files and used for software documentation. Texinfo is the official documentation format of GNU. Check out this asciicast for a live demonstation:

Installation

Install it like any other Vim plugin. You must have at least version 6.4 of the GNU Info command-line tool installed on your system (older versions might work, but I haven't tested them). You can set the binary by setting the g:infoprg variable to its path.

Quickstart

This plugin is still very much under construction, so any of this may change in the future. There is a interactive tutorial available via :Info info.vim. To open an Info document run

" Open the directory listing
:Info
" Open a particular document
:Info <file>
" Same as above, but jump to specific node
:Info <file> <node>

The placeholder <file> is the topic you want to read about, e.g. :Info bash to read the manual for the Bourne Again Shell. Alternatively you can also open a buffer with a URI pattern like this:

:edit info://
:edit info:<file>
:edit info:<file>#<node>

You could call :e info:bash in a buffer to open the same document as above.

Use the :Menu command to follow a node's menu entries.

" Display menu in location list
:Menu
" Jump to entry 'Introduction'
:Menu Introduction
" Short form works as well
:Menu intro

You can also use tab completion with the :Menu command.

You can follow cross-references using the :Follow command:

" Display all cross references in location list
:Follow
" Follow a named cross-reference
:Follow Name of the reference

Use the K key in normal mode to follow the reference under the cursor, works for both menu entries and cross references.

Navigation

Use the commands :InfoUp, :InfoNext and :InfoPrev to navigate to respective node. Alternatively, add mappings like these to your settings.

" Only apply the mapping to generated buffers
if &buftype =~? 'nofile'
    nmap <buffer> gu <Plug>(InfoUp)
    nmap <buffer> gn <Plug>(InfoNext)
    nmap <buffer> gp <Plug>(InfoPrev)
endif

You can access the menu via the :InfoMenu command. It supports tab-completion, and if no argument is given all menu items are listed in the location list. If you want a prompt similar to standalone Info use a mapping like this:

" Only apply the mapping to generated buffers
if &buftype =~? 'nofile'
    nmap <buffer> gm <Plug>(InfoMenu)
endif

You can follow a cross-reference using the :InfoFollow command. You can remap the prompt to something more convenient:

" Only apply the mapping to generated buffers
if &buftype =~? 'nofile'
    nmap <buffer> gf <Plug>(InfoFollow)
endif

Other cool stuff

You can set Vim as your default standalone Info reader with this little trick:

# Create a shell function as a wrapper
viminfo () {
    vim -R -M -c "Info $1 $2" +only
}
# Alias info to our new function
alias info=viminfo

This snippet creates a shell function which invokes Vim with the :Info command and splices in the command-line arguments. We can alias it to info if we want to replace the standalone Info reader. Add the above lines to your shell configuration file to make it permanent.

Stuff left to do

The goal for the first stable release is feature-parity with standalone Info. These features depend on support from standalone Info, so my hands are tied for the time being.

Index lookup (:Index command)
Search within a file (:Search command)
Going to a specific node in the file (:Goto command) (implemented, but without tab-completion)

Self-promotion

If you like this plugin please consider financially supporting its development, every small amount helps; you can become a regular supporter through LiberaPay or tip me with a one-time donation over Ko-Fi. Feel free to explore my other software projects as well.

info.vim's People

Contributors

Stargazers

Watchers

Forkers

milly jaawerth mburz dundargoc loyalpartner

info.vim's Issues

Use `info://...` for buffer name

Thanks for nice plugin!

Currently, info.vim uses info:... format for buffer names. I suggest changing it to the standard info://... format, following many other plugins, e.g. fugitive://, man://, fern://.

Vim always interprets a filename that starts with scheme:// as an absolute path, so it removes ambiguity. For example, there can be a file named info:... in cwd. This is why :h Cmd-event recommends this format. This also allows ignoring the info buffers in :oldfiles with set viminfo+=rinfo://.

Deprecated project

It seems this repo is "deprecated" in favor of the one on Gitlab. It would be good if you made this clear on the README and/or description.

Using <C-o> to go back to the last jump point freezes Vim

When inside an Info documentation, I can move around without any problems and follow link to and from different Info nodes without any problems. However, during normal Vim usage, I usually like to go back to my previous point using , which inside an Info document seem to freeze Vim completely.

I don't know if that's a problem coming from my side, or from the plug-in itself (I haven't tested it without any other plug-ins yet, I could try that if needed).

Otherwise thanks for providing this plug-in, I haven't had any other problems using it and it looks great!

Additional optional mapping

I added these mappings:

nmap gg K

"use fzf for the menu
nmap gm :call fzf#vim#buffer_lines('* ', 0)

There's probably a much better way to find the nodes names than just searching for "* "

Missing InfoMenu

The README mentions there is both a :Menu command and a :InfoMenu command. But when I load the plugin, I only get a :Menu option.

I'm working around right now with custom commands, but having :InfoMenu and other aliases like :InfoFollow etc built-in would be nice to have. A common style I use to for Vim plugins is to type the command prefix (e.g. :Info) and use tab-completion to quickly see what's available.

Useful plugin though, thanks!

Respect extra parameters for man fallback

For example, :Info git init falls back to the default git page, while :Man git init shows the right page.

What should the command for 'next' and so on be called?

This family of commands is used for navigating to related neighbouring nodes. Here are my suggestions, keep in mind that these commands will only be available in info buffers:

" append node (currently in use)
:UpNode
:NextNode
:PrevNode

" Prepend info
:InfoUp
:InfoNext
:InfoPrev

The variants with Info prefix are guaranteed to have at least four suggestions for the first four letters when tab-completing, and unlikely to have more. On the other hand, the suffix versions are unpredictable, they might complete immediately or the user might get a lot of suggestions if other plugins use a similar naming scheme.

Opinions?

<Plug> mappings

I noticed that the <Plug>Info* mappings do not use the "parentheses trick". <Plug>InfoFoo will trigger a wait for mapping to complete if there is also a <Plug>InfoFoo2 mapping defined.

The wait would be avoided if they were defined as <Plug>(InfoFoo) and <Plug>(InfoFoo2) . In other words, it's a good practice to always wrap <Plug>(...) mappings in parentheses.

Just FYI in case you didn't already know.

propose shell function

To supplement the built-in info reader, how about proposing in the docs a function, named say vinfo in .bash/zshrc that calls :Info, for example

vinfo() {
  vim +"Info "$@"" +only
}

`Info.vim: falling back to manpage`

Thanks for this plugin.

Executing e.g. :Info ls returns the error Info.vim: falling back to manpage. Running info ls on the regular command line shows the expected page.

Executing :Info works without issues, and following a couple of links I am able to reach that page about ls (info:coreutils.info#ls%20invocation).

By the way, the tutorial mentions :InfoGoto XRef-Navigation. I think this should be :Goto XRef-Navigation.

Add support for looking up non-Node indices

Info supports looking up indices that are not Nodes.
For a list of what indices you could look up you could run info --apropos=

I added support for this on my fork, but it's more of a crud quick hack than something nice, hence I won't be creating a PR, but you could look at it here:
https://github.com/mburz/info.vim