How to create an index that lists topics from multiple help files?

Question

I started writing a help file for various vim commands that I know I'll forget.

Over the last 7+ years it's grown to ~1600 lines and is starting to become unwieldy

I've been trying to split it into one file per topic, similar to the vim help files eg user01.txt.

I copied one of the topics, called it sfsearch.txt

and tried to make the main help, sfcontents.txt file jump to sfsearch.txt when I used CTRL-]on sf-search.txt for eg . I tried |sf-search.txt| and *sf-search.txt* and tried to understand the help documentation but have had no luck.

I can use :h sf-search.txt when in a file but I can't do :h sf-index and then CTRL-] on sf-search.txt within sf-contents.txt. No error or complaint. Just won't open it. Both files are in the same directory.

Any suggestions?

Update I stopped being a guy who taught himself bash scripting around 20 years ago and I didn't know the terminology then as I was a stored procedure developer / BA then so if I have the terminology wrong apologies. I never understood *nix style help files due to that.

Update 2 After the comments from Romainl and Martin Tournoij I checked the function and the Helptags call is there.

I also used :helptags $VIM/vimfiles/doc/ from a new window and it didn't work for either defining *sfsearch.txt* or |sfsearch.txt| in sfcontents.txt

function! helpFile()
  :silent! !copy "c:\workdocs\vimutils\vimtips\commands_back.txt"         "C:\workdocs\vim\vimfiles\doc\sfcontents.txt" 
  :silent! !copy "C:\workdocs\vimutils\help\usefulcommands.txt" "C:\workdocs\vim\vimfiles\doc\sfuseful.txt"
  :silent! !copy "C:\workdocs\vimutils\help\sfsearch_back.txt" "C:\workdocs\vim\vimfiles\doc\sfsearch.txt"
  :chdir $VIM/vimfiles/doc
  :Helptags $VIM/vimfiles/doc/
  "I also tried the following without success
  :helptags $VIM/vimfiles/doc/
endFunction

Answer 1

I can see a handful of potential problems here.

In rough order of the likelihood that they are what's breaking things for you. I'm trying to cover all the possibilities, so apologies for anything that you are already aware of in the below:

Tag naming consistency

In your screenshots, it looks as though you've named your help files and set up the help tags for those filenames (the targets, marked in the help files with *asterisks*) without hyphens, but your hot-links (marked up with |vertical bars|) include hyphens. The links and targets need to match exactly to work correctly.

Location of files

You're using the $VIM environment variable in the path you pass into the :helptags command, but the !copy commands above use absolute paths. Is there any chance you don't actually have $VIM set to point to this location? What is the output of :echo $VIM? After you run the :helptags command, can you see a tags file in the directory alongside sfsearch.txt? If you open the file, does it contain an entry for sfsearch.txt?

Location of files, again

Even if the tags file is generated correctly, it will only be picked up by Vim if it is in a doc directory that itself is within one of the paths in your 'runtimepath' setting. What is the output of :set rtp? Does it contain an entry for C:\workdocs\vim\vimfiles\?

N.B. For just the CTRL-] command, you could also tell Vim about the tags file via the 'tags' option. This won't affect the behaviour of :help, though, so setting rtp correctly is preferred.

Tag/hot-link syntax

The highlighting in the screenshots look as though you've set this up correctly, but the text of your question suggests some uncertainty about the syntax:

I tried |sf-search.txt| and *sf-search.txt*

[...]

it didn't work for either defining *sfsearch.txt* or |sfsearch.txt| in sfcontents.txt

The targets of the links should be marked up with asterisks, and the links that you want to navigate from should be surroudned by vertical bars. Can you confirm this is how they were written during testing?

Answer 2

The way Vim looks up the references in helpfiles is through a tags file which records where each tag is located. For the built-in Vim help you don't really notice this because the tags file is shipped with Vim, so it "just works".

You can create tags with :helptags <dir>, or :helptags ALL for all directories. However, for this to work the files must be located within a doc directory of the runtimepath setting. The easiest would probably to just create a symlink in the plugin directory; assuming you keep your custom Vim doc files in ~/vimdoc:

% mkdir -p ~/.vim/pack/plugins/start/vimdoc
% ln -s ~/vimdoc ~/.vim/pack/plugins/start/vimdoc/doc

Then run :helptags ~/vimdoc or :helptags ALL and references should work. You'll have to re-run that every time you add a new tag.