Inline Help

The inline help utility allows quick access to command and FISH reference data. Additionally, it may be used to enter keywords/functions at the current cursor position — either in the active workspace or at the command prompt.

../../../../../../../../_images/inline_help_1.png

Keyboard Commands

The utility is oriented toward working from the keyboard, with the following keyboard commands available when the utility is in focus.

Keystroke

Command

ctrl + spacebar

first: open the utility

ctrl + spacebar

subsequent: toggle focus between the inline help utility and the current cursor position

Esc

close the utility window (also x)

Enter

type the current selection at the current cursor position

move up one line

move down one line

→/←

open/close the current item on the tree (no effect if the current line is not a container item)

F1

open the documentation to the reference page for the current selection in the utility*

F2

open the documentation to the present topic (also h)

F3

open the filter field (also f, see Filter below)

*Items in bold will not open to a reference document

Mouse

The operations above are accessible via mouse operations. The tree control containing commands/FISH will behave as expected; the other operations are described below.

Usage

Given a cursor position in either an input file in the workspace or the command prompt in the Console tab, the Inline Help utility will open to the command, keyword, or FISH function indicated by that position, if possible.

In the utility, commands and FISH functions are listed alphabetically, showing the basic form of their signatures. See the topic Command and FISH Reference Notation in the Documents for details. Items shown in bold indicate an entry that does not have a corresponding reference document.

Once opened, the utility may be used to insert any selected command, keyword, or FISH function, any number of times.

The tool will remain open indefinitely until closed using either the x button or pressing Esc while the utility has focus.

The complete set of operations with the utility follows.

Open

ctrl+spacebar or open

Open the utility. The open button is found at the far right of the command prompt in the Console tab, or at the far right margin of the current line in an input file in the Editor workspace.

Note the commands tree and the FISH intrinsics tree are mutually exclusive; the correct one is shown when the utility opens. Traversal from one tree to the other is not possible from within the utility.

Toggling Focus

ctrl+spacebar or mouse click

Once opened, pressing ctrl+spacebar again will toggle focus between the current cursor position and the utility window. Alternatively, the mouse can be used to put focus on either the workspace or the utility window.

While focus is at the cursor, the utility remains present. Editing operations may proceed as normal in the input file/command prompt.

If focus is put on the workspace and the cursor is moved, when returning focus to the utility the presentation of the tree will shift from its last state to a new view that reflects the command/keyword/function at the current cursor position.

Text Insertion

Enter or right click and select Insert selected

There are two important behaviors to note:

  1. Only the keyword or function will be typed. Values, optional keywords, or arguments for the current selection will not by typed.

  2. Because tree navigation in the utility is not restricted to the current cursor position, it is possible to navigate to a remote location in the tree and insert a command/keyword/function that could not logically be used at the current cursor position.

As mentioned above, items in bold are group headings and as such will not open to a reference document when F1 is pressed.

Close

Esc or x

Once the utility is closed, focus is returned to the current cursor position.

Filter

F3 or f

When accessed, the filter tool provides a field that allows the user to restrict the tree view to entries that match the text entered in the field.

../../../../../../../../_images/inline_help_2.png

Keyboard and mouse operations after the tree is filtered are as normal (e.g., insert, move up or down the tree, get help on selected, etc.). Dismiss the filter by pressing F3 again, or using its x button.

Help

F1 or right click and select Help with current selection...

The reference document associated with the currently selected line in the utility opens when F1 is pressed.

F2 or h or right click and select Help with Inline Help utility...

This page is opened when F2 is pressed.

In Practical Use

Good Initial Cursor Position

Tip

The utility may be called from a blank line — in which case the tree will be opened at its topmost level (i.e., it will show all the main groups of commands or all the main FISH intrinsics groups).

The utility presents the command or FISH intrinsic tree based on the current cursor position. Though the user may obtain the desired information while the cursor is within a command/keyword/function, a better first result is likely if the utility is called from a cursor position to the immediate right of the current command/keyword. With FISH, this would be to the immediate right of the dot in the function’s name.

Remember to Add Values, Options, and Arguments

The utility does not insert values or options that are part of a command, nor does it add arguments to FISH functions.

For instance, given a selected line in the utility such as this:

zone create fred <range>

On pressing Enter the utilty would type:

zone create

Remember Where the Cursor Is

Tip

If lost in the tree, to get back to the initial position it may be easiest to press ctrl+spacebar twice.

While it is very useful to be able to traverse the tree in its entirety, always remember that the utility does not perform any syntax validation. Nothing stops use of the utility to insert commands/keywords/functions where they do not belong and that will result in error when the program executes that line of input.