On 05/06/09 17:03, Charles Campbell wrote:
>
> roy nyc wrote:
>> 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?
>>
> 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
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
--~--~---------~--~----~------------~-------~--~----~
You received this message from the "vim_use" maillist.
For more information, visit http://www.vim.org/maillist.php
-~----------~----~----~----~------~----~------~--~---
