# Help files

### Help file syntax.

The following control statements can be used in help files.

Control statement | Description
--- | ---
@Topic (at the beginning of a line) | Starts a topic definition. There are four topics with special names: The topic with the name Contents has a special meaning. It is shown when `F1` is pressed in the FAR command line when the plugin is active or when an item is selected from the plugins help list. If a plugin can be configured, it is recommended to specify Config as the name of the help topic for the configuration dialog. This topic will be shown when `F1` is pressed in the plugins configuration menu (Options|Plugins configuration). If a plugin can be invoked both in the panels and in the editor or viewer and has different functions depending on where it was invoked, it is recommended to use topics Editor and Viewer for describing the operation in the viewer and editor, respectively. These topics will be shown when `Shift-F1` is pressed in the list of plugin commands in the viewer or editor.
$Text (at the beginning of a line) | Defines a non-scrolling region. All lines starting with $ must be in the beginning of a topic (immediately after the line starting with @) and will be shown in a non-scrolling region, delimited from the rest of the text with a horizontal line.
~Text~@Topic@ | Reference to a topic. If you wish to access a topic from the main FAR Manager help from inside plugins help, precede the topic name with a colon ('`:`'). The reference must not be split on mutiple lines.
~Text~@<FullPath>Topic@ | Reference to a topic in a help file located at a folder with full or relative path of FullPath. An ending backslash must be added. The reference must not be split on mutiple lines. For example, the plugin Foo is located in folder 'D:\FAR\Plugins\Foo' and we need to show the topic 'FooInfo' from its help file.
    ~About Foo~@<D:\FAR\Plugins\Foo\>FooInfo@
~Text~@<FullModuleName>Topic@ | Reference to a topic in a help file located at the same folder as the plugin with the relative or full path of FullModuleName. The reference must not be split on mutiple lines. For example, we need to show the help topic 'FooInfo' from the help file of the plugin Foo 'D:\FAR\Plugins\Foo\Foo.dll'.
    ~About Foo~@<D:\FAR\Plugins\Foo\Foo.dll>FooInfo@
~Text~@URL@ | URL activator, allowing to run applications that support URL protocols. The following list shows the protocols that can be used in help files:
    ~File access protocol~@file://C:\Program Files\Far\License.txt@
    ~File transfer protocol~@ftp://ftp.kgb.ru/WinUtil/Rar/@
    ~HTTP~@http://plugring.farmanager.com/@
    ~MailTo~@mailto:vskirdin@@mail.ru@
    ~News~@news://fido7.far.support@
    ~Telnet~@telnet://fido7.far.support@
The reference must not be split on mutiple lines.
#Text# | Highlights the text Text.
^ (at the beginning of a line or after $) | Centers the line.
@- (at the beginning of a line) | Disables text auto format. By default FAR formats all lines in which text starts from the first position (is not indented). Must be placed in a separate line.
@+ (at the beginning of a line) | Enables text auto format. Must be placed in a separate line.
<CtrlColorChar>XX | Specifies a color attribute that will be used to display the text following it. The color attribute XX consists of two hexadecimal digits (0-9A-F). For example, the backslash ('\') character is set to be the color specifying character (<CtrlColorChar>). Then the statement `\4F` will force the help manager to output the following text with white letters on dark red background. (see CtrlColorChar)
<CtrlColorChar>- | Specifies that the following text must be displayed in default colors. (see CtrlColorChar)

### Remarks

1. The length of a text string in a help file must not exceed 300 characters.
2. If you need to display the characters ~, # or @, duplicate them (~~, ##, @@).
3. In the <URL> field of URL activators, the ~ and # characters may be duplicated or specified once, but the @ character must be always duplicated. If the URL must contain a sequence of two ~ or # characters, specify a sequence of 3 or 4 characters (for example, ~~~ and ~~~~ will be shown as ~~).
4. Don't use special characters ~, # or @ inside a reference that is not an URL activator.

### Example

The following example is taken from the `FarEng.hlf` file.

    @FolderShortcuts
    $ #Folder shortcuts#
        Folder shortcuts are designed to provide fast access to frequently
    used folders. Press Ctrl-Shift-0..9, to create a shortcut
    to the current folder. To change to the folder recorded in the shortcut,
    press RightCtrl-0..9. If RightCtrl-0..9 pressed in edit line, it inserts
    the shortcut path into the line.

        The #Show folder shortcuts# item in the ~Commands menu~@CmdMenu@ may be
    used to view, set, edit and delete folder shortcuts.

It looks like this:

The following examples demonstrates usage of the URL activator.
E-mail client activation:

    ~vskirdin@@mail.ru~@mailto:vskirdin@@mail.ru@

Browser activation:

    ~http://plugring.farmanager.com/~@plugring.farmanager.com/@

or

    ~http://www.uic.nnov.ru/~~ruiv/plugring/~@http://www.uic.nnov.ru/~ruiv/plugring/@

The following example demonstrates usage of color attributes:

    .Language=English,English
    .PluginContents=Reversi - Game
    .Options CtrlColorChar=\

    ...

    @-
             Reversi, also known as Othello, is a strategy game
     \70 B \-\2F W \-  played by two players:  Black and
     \2F W \-\70 B \-  #White#.  It is played on an 8x8 board
             using 64 disks with different color on each side.
    @+

It looks like this:
See also:
Control statements, Language files