FunctionHelp plugin for Take Command

beta version 0.92.2 2021-12-21

Charles Dye

Purpose:

This plugin implements status-bar help for TCC functions. When you type the name of a function, FunctionHelp displays the function’s syntax in the status bar. If you mouse over the status bar, a popup will show more information.

Installation:

To use this plugin, copy FunctionHelp.dll to some known location on your hard drive. (If you are still using the 32-bit version of Take Command, take FunctionHelp-x86.dll instead of FunctionHelp.dll.) The included text file FunctionHelp.txt contains the help text to be displayed. This file should either go in Take Command’s program directory, or else in the same location as the .DLL file.

Load the .DLL file with a PLUGIN /L command, for example:

plugin /l c:\bin\tcmd\test\functionhelp.dll

If you copy this file to a subdirectory named PlugIns within your Take Command program directory, the plugin will be loaded automatically when TCC starts.

Operation:

This plugin provides on-the-fly syntax help for TCC functions. It displays this information in the status bar, like the built-in syntax help for commands. FunctionHelp communicates with Take Command to display its help text. It won’t work in a standalone console TCC session, or in console replacements like ConEmu or Console2. Nor will it work in TCC/LE, unless you are running the long-defunct Take Command/LE. Note that TCC and Take Command must be the same version for the interprocess communication to work.

Help text for functions is stored in a text file, which is automatically loaded when the plugin starts. You can edit this file with any text editor to change the help text, or to add new functions. Your changes will not take effect until the file is reloaded, either by unloading and reloading the plugin, or by the FUNCHELP command.

Each function takes one line in the file; each line must begin with an @ sign. Any line not beginning with an @ is ignored. If a function appears more than once in the file, the last line wins.

The plugin watches for the [ and ] keys. When you type a [, the plugin scans the command line. If there is a function name to the left of the cursor, FunctionHelp will look for the appropriate help text, and display it if found. When you type the matching ], the function will be ‘closed’ and its help text removed.

The plugin will not load in transient or pipe shells. In a non-interactive shell, it would only waste memory.

Automatic Load:

When FunctionHelp starts, it looks for its data file:

In the Take Command install directory
In the same directory as FunctionHelp.dll
Per a FunctionHelp environment variable

I suggest the first option, the Take Command program directory. Different versions of TCC support different internal functions. Keeping the data file in the program directory allows you to customize it to the specific version of Take Command in use.

Syntax Note:

The syntax definitions in the following text use these conventions for clarity:

`BOLD CODE`	indicates text which must be typed exactly as shown.
`CODE`	indicates optional text, which may be typed as shown or omitted.
Bold italic	names a required argument; a value must be supplied.
Regular italic	names an optional argument.
ellipsis…	after an argument means that more than one may be given.

New Command:

FUNCHELP — Load or reload the FunctionHelp data file, or display info.

Syntax:
FUNCHELP /I /L:filename /Q

`/I`	show detailed memory usage info
`/L:`filename	load or reload the data file
`/Q`	quietly

If you load help text with /L, the text from the file will replace any currently loaded help text. If the file does not contain any function help text, then the currently loaded help will not be changed.

Startup Message:

This plugin displays an informational line when it initializes. You can disable it by defining an environment variable named NOLOADMSG, for example:

set /e /u noloadmsg=1

Status and Licensing:

Consider this beta software. It may well have issues. Try it at your own risk. If you find a problem, you can report it in the JP Software support forum.

FunctionHelp is currently licensed only for testing purposes. I may make binaries and source code available under some free license once I consider it ready for use.

Download:

You can download the current version of the plugin from http://prospero.unm.edu/dl/functionhelp.zip or ftp://prospero.unm.edu/functionhelp.zip.

— Quick Links —