Home Explore Blog CI



neovim

6th chunk of `runtime/doc/helphelp.txt`
7fc114eb0d0e6a92f7771a1dc9879c6d3e3b8da3e6c2f2410000000100000c24
 following format: >

	*plugin_name.txt*	{short description of the plugin}

The first field is a help tag where ":help plugin_name" will jump to.  The
remainder of the line, after a Tab, describes the plugin purpose in a short
way.  This will show up in the "LOCAL ADDITIONS" section of the main help
file.  Check there that it shows up properly: |local-additions|.

If you want to add a version number or last modification date, put it in the
second line, right aligned.

At the bottom of the help file, place a Vim modeline to set the 'textwidth'
and 'tabstop' options and the 'filetype' to "help".  Never set a global option
in such a modeline, that can have undesired consequences.


TAGS

To define a help tag, place the name between asterisks ("*tag-name*").  The
tag-name should be different from all the Vim help tag names and ideally
should begin with the name of the Vim plugin.  The tag name is usually right
aligned on a line.

When referring to an existing help tag and to create a hot-link, place the
name between two bars ("|") eg. |help-writing|.

When referring to a Vim command and to create a hot-link, place the
name between two backticks, eg. inside `:filetype`.  You will see this is
highlighted as a command, like a code block (see below).

When referring to a Vim option in the help file, place the option name between
two single quotes, eg. 'statusline'

When referring to any other technical term, such as a filename or function
parameter, surround it in backticks, eg. `~/.path/to/init.vim`.


HIGHLIGHTING

To define a column heading, use a tilde character at the end of the line,
preceded by a space. This will highlight the column heading in a different
color.  E.g.

Column heading ~

To separate sections in a help file, place a series of '=' characters in a
line starting from the first column.  The section separator line is highlighted
differently.

							      *help-codeblock*
To quote a block of ex-commands verbatim, place a greater than (>) character
at the end of the line before the block and a less than (<) character as the
first non-blank on a line following the block.  Any line starting in column 1
also implicitly stops the block of ex-commands before it.  E.g. >
	function Example_Func()
	  echo "Example"
	endfunction
<
To enable syntax highlighting for a block of code, place a language name
annotation (e.g. "vim") after a greater than (>) character.  E.g. >vim
	function Example_Func()
	  echo "Example"
	endfunction
<
						*help-notation*
The following are highlighted differently in a Vim help file:
  - a special key name expressed either in <> notation as in <PageDown>, or
    as a Ctrl character as in CTRL-X
  - anything between {braces}, e.g. {lhs} and {rhs}

The word "Note", "Notes" and similar automagically receive distinctive
highlighting.  So do these:
	Todo	something to do
	Error	something wrong

You can find the details in $VIMRUNTIME/syntax/help.vim


FILETYPE COMPLETION					*ft-help-omni*

To get completion for help tags when writing a tag reference, you can use the
|i_CTRL-X_CTRL-O| command.


 vim:tw=78:ts=8:noet:ft=help:norl:

Title: Help File Formatting: Tags, Highlighting, and Filetype Completion
Summary
This section details the formatting conventions for Vim help files, including defining tags with asterisks, creating hot-links to existing tags, Vim commands, and options using bars, backticks and single quotes respectively. It also describes highlighting conventions for column headings, section separators, and code blocks, and lists automatically highlighted words like 'Note' and 'Todo'. Finally, it covers filetype completion for help tags using the |i_CTRL-X_CTRL-O| command.