creating Vim help files

[roy nyc]

I'd like to create help files that display correctly in the Vim help
facility and a set of companion files that display correctly at cross-
linked HTML pages.

What's the best approach?

[Charles Campbell]

Can't help you with the cross-linked HTML pages (perhaps the utl.vim
plugin would be of interest), but as for help pages:

put 'em into ~/.vim/doc
run :helptags ~/.vim/doc

(see :he helptags)

Regards,
Chip Campbell

[Tony Mechelynck]

In some more detail:

- User help files should have extension .txt and their first line should
be a one-line summary of what the file does, for inclusion in the "LOCAL
ADDITIONS" section near the bottom of |help.txt|. (Vim includes the
first lines automagically, you don't need to touch
$VIMRUNTIME/doc/help.txt). That first line should start with the name of
the file itself, with the .txt extension, and between stars.

- User help files should be in the doc/ subdirectory of one of the
directories in 'runtimepath', but not in $VIMRUNTIME/doc/ because any
upgrade may (and someday one certainly will) silently remove any changes
you bring to the $VIMRUNTIME tree, which is meant _only_ for files
distributed together with Vim. Normally this means that your "user"
helpfiles will be named something like ~/vimfiles/doc/filename.txt on
Windows or ~/.vim/doc/filename.txt on most other OSes. Another
possibility, if you have sysadmin privileges, is to add some of them for
all users on your system, installing them as (on any OS)
$VIM/vimfiles/doc/filename.txt

- Use *stars* to create a point to which the user can jump, then bars
used like |stars| will jump to it. Or if you define options, have a
header like *'option'* just above the definition, then 'option' will
jump to it (but you would of course need to patch the C code to create a
new option). You can jump to tags in existing helpfiles the same way,
e.g. |help.txt|, |bars|, 'compatible'.

- There are other "invisible characters" used in help files to change
the color of the text; you may want to look at some existing helpfiles
in a Vim session with no syntax highlighting (or in a stripped-down
"tiny vim" with no syntax highlighting capabilities, or in a text editor
other than Vim) to see how it is done.

- Running the ":helptags" command on the .../doc/ directory containing
your new helpfile is the essential "trick step" required to include it
in the Vim help system.

See $VIMRUNTIME/macros/matchit.txt for an example of a helpfile meant to
be included as a "user helpfile" in the manner described above.

Best regards,
Tony.
--
"OK, now let's look at four dimensions on the blackboard."
-- Dr. Joy

[Matt Wozniski]

On Sun, Jun 7, 2009 at 9:40 PM, Tony Mechelynckwrote:

>
> - There are other "invisible characters" used in help files to change
> the color of the text; you may want to look at some existing helpfiles
> in a Vim session with no syntax highlighting (or in a stripped-down
> "tiny vim" with no syntax highlighting capabilities, or in a text editor
> other than Vim) to see how it is done.

Or dive into $VIMRUNTIME/syntax/help.vim if you're feeling
enterprising. And, another option is to make the Ignore highlight
group not be invisible - make it almost but not quite invisible and
you'll get the hang of how other help files are using those special
markup symbols pretty quickly.

~Matt