How do I create my own tag files with Vim for interconnected non-code text?

Question

I'm writing a fair bit of interconnected non-code text in vim, and I'd like to generate my own tags to use with vim tagging.

For example, there's a file all about "foo", and ideally, whenever I'm editing the files "bar" and "baz" and the word "foo" comes up, I'd like to be able to hit ^] and jump to the foo file, and then hit ^T and jump back to wherever I was.

Is there any way for me to make my own tag files where the word "foo" points to the file "foo" and so on and so forth? Every source that I have checked just explains how to use ctags to generate tags for every programming language under the sun, but I'd just like to be able to create a simple tag file of my own.

Answer 1

If I understood right (and that's a capital IF) what you are looking for is basic vim help functionality. You define a tag (some_word) a lot of jumppoints (|jumppoint|) and that's it.

Without going into the details I'd really recommend you glance through the

:help tags

help file. It will explain a lot. I haven't done this in a while, but basically it comes down to this. You need to define tags (**), and then introduce them into vim's tag system via :helptags command. After that, don't move them, and when using jumppoints it will lead you to them via already mentioned Ctrl-] and T.

ctags and the like should not worry you ... this is completely vim's functionality, and they have nothing to do with it (they only come into the story when code comes into it ... and even then, in some cases, if you're willing to do some manual labour they can be avoided).

Answer 2

:help tags-file-format

will give you some pointers on how to write a tags file. But you basically need lines like:

tagname TAB tagfile TAB location

The location can any Ex command; it could be a line number, but is usually a search pattern like /\<foo\>/ or /^Where is foo?$/ so that the tags don't need to be regenerated each time you edit your files.

Answer 3

I have been wanting to write some docs with the tag features found in vim help but I couldn't find anything online that had a simple and specific solution. So for anyone who may currently be looking for a quick solution to this, I will share what I have found.

The quickest way to get up and running:

Lets say you are working in an empty folder.

If you create a file such as this test.txt:

|topic1|
*topic1*

Then run:

:helptags ./

Vim will generate a file (tags) in the current dir (./) that will let you jump (ctrl+]) from |topic1| to *topic1*

If you open up the tags file you can see its simplicity:

topic1   test.txt    /*topic1*

Format:

[key word][TAB][file][TAB][command]

You can add other tags to this file and they will work right away.

Of course the best part of tags is the ability to jump to definitions in other files which can be accomplished by changing the [file] argument in the tags file. Again, you will need to have a |tag| in the parent file and a *tag* in the child file for it to work.

Writing the tags file from scratch also seems to work without issue if it is named "tags" and you run :helptags ./ in vim afterwards.

Note:

As others have mentioned in this post, :help is your friend. If you enjoy vim, you should spend some time flipping through the manual, everything is very well documented. If you don't enjoy vim, you can still use the manual for quick searches. In my experience, I can usually get to a solution through the man pages faster than I can searching online. Just remember the following:

/

to start searching

ctrl+]

to jump to file / definition

ctrl+o

to jump back

These basic navigation commands are also displayed as soon as you open :help

Answer 4

A simple tag format that will work with just about any version of vi/vim, and can be easily created/edited by hand (still with vim), is the name of the tag, the file path, and the line number, separated by a tab.

I use a php command line script to scan my code and generate tags with this format, printing lines: "$tagname\t$filepath\t$lineNo\n"; to the tags file.