Randomly select a documentation article

Question

I wanted to know if there is some way of fetching a random "article" (maybe article is not the proper term here) from the vim documentation.

I found nearly nothing on the subject on vim documentation and on internet.

One of my ideas was to list every file of documentation and then pick one randomly. But even "list every file" or "list every article" ...

I found that with one character, there is a possibility to have a list :

:h a<Tab>

This expands to a list of (I think) a list of every help entry available...

Any idea ?

Answer 1

I think the 'article' you're looking for is 'help tag' - if so, look no further than:

https://github.com/mhinz/vim-randomtag

Answer 2

The documentation files are stored are text files in $VIMRUNTIME/doc. You can start the documentation by just calling one of the filesnames, eg: :help usr_41.txt

You can get a list of these files with the glob() function:

:echo glob("$VIMRUNTIME/doc/*.txt", '', 1)
['/usr/share/vim/vim74/doc/arabic.txt', '/usr/share/vim/vim74/doc/autocmd.txt', ...]

However, as far as I know there is no straight-forward way of getting a random item of a list, but How to generate random numbers? lists a number of work-arounds. All them use an external tool to do so.

Since we're using an external tool (I used Python here) , we might as well use that for getting the files:

:py import glob, random; print(random.choice(glob.glob(vim.eval("$VIMRUNTIME") + '/doc/*.txt'))
/usr/share/vim/vim74/doc/indent.txt

And to open a help page:

:py import vim, glob, random, os; vim.command (':help ' +  os.path.basename(random.choice(glob.glob(vim.eval("$VIMRUNTIME") + '/doc/*.txt'))))

As a one-liner it's a bit unreadable, so here's a script which does the same, but more readable:

fun! RandomHelp()
python << EOF
import vim, glob, random, os
all_pages = glob.glob(vim.eval("$VIMRUNTIME") + '/doc/*.txt')
random_page = os.path.basename(random.choice(all_pages))
vim.command(':help ' + random_page)
EOF
endfun

Or if you don't have Python, you could use the shell:

:execute ':help ' . system("ls $VIMRUNTIME/doc/ | shuf -n1")

Note that shuf is a non-standard tool, and may not be available on your system.

Answer 3

Your "article" may correspond to the tags created with :helptags and which divide the help files into subject sections (see :help helptags) and are the section names that you can see when you complete your help command with :help a<Tab> or :help a<C-D>. They live in a tags file in $VIMRUNTIME/doc/tags. The first five lines of mine are

!        change.txt    /*!*  
!!       change.txt    /*!!*  
#        pattern.txt   /*#*  
$        motion.txt    /*$*  
$HOME    options.txt   /*$HOME*

You can extract a list of all the help tags from this file, but how to best do that may depend on how you're going to use the list. If for example you want to use this list with Vim's help command, then you may want to read the first field of each line of this file and then execute the help command with the content of that field. If on the other hand you want to read off content of the help section to use somewhere outside of Vim's help, you may be better served by using the second field to locate the correct file for a topic and the third field as a search pattern to find the section. If you do this, then remember that you should indicate that the pattern is not magic (i.e., begin the pattern with \M or \V) since the * in the third field of the tags file is a literal asterisk, not the pattern multi item (:help /star) with the same name.

Answer 4

I was looking for the same ability and ended up on these solutions. I ended up modifying what I have learned from the answers I found here and decided to share what I learned.

Thanks jjaderberg for showing me about the $VIMRUNTIME/doc/tags file as this made jumping to a random help file very easy using a bash shell.

Add the following function and mapping to your vimrc file for a simple way to generate a random help entry:

function! HelpRandom()
    " Using the shell, produce a list of all help tags and select one (based on $VIMRUNTIM/doc/tags)
    execute "normal! :help " . system("cat $VIMRUNTIME/doc/tags | shuf -n1 | awk '{print $1;}'")
endfunction

" Display a random help entry
nnoremap <leader>?? :call HelpRandom()<CR>  

Please note that the "system" command is for a *nix system and will need to be adjusted for Windows.