a4.1 man page

NAME

a4 - a dynamic terminal manager

SYNOPSIS

a4 [-h|-?] [-i file] [-s] [-v]

DESCRIPTION

a4 is a dynamic terminal window manager. One of eight tiling layouts is dynamically applied to all visible terminals. The terminal windows are grouped by tags making it easy to visually switch between contexts of work. Color schemes are dynamically applied to each terminal window, based on the text in its titlebar, helping the user to visually identify terminals based on attributes such as hostname, userid, and any other text programmed to display in the titlebar.

Four of the eight layouts divide the screen into two areas, one for a zoomed window and the other for a stack of the remaining windows. These four layouts can be adjusted during use to expand or shrink the number of windows in the zoom area and the overall size of the zoom area. They are named for the location of the zoom area: zoom_left, zoom_right, zoom_top, and zoom_bottom. The other four layouts are fullscreen, grid, rows, and columns.

Each terminal window can be tagged with one or more tags. The user then selects which tag or tags to view, and all windows with those tags are arranged in the dynamic layout. The list of all tags is displayed on the left of the status bar. Tag names are user defined with the default being the numerals 1 through 9.

Terminal windows can be minimized to a bar at the bottom of the screen. A minimized terminal keeps its tags but stays out of the user's way until it is unminimized again. Terminal windows can be set to read-only status in order to prevent accidental typing or closing. Terminal windows can be added to a focus group in order to type the same input into all simultaneously. Minimized and read-only terminal windows are never typed into, even if they are included in the focus group.

Terminal color schemes are dynamically applied by comparing the text of the terminal's title with an ordered set of user-defined color rules.

OPTIONS

-h, -?: Prints a brief usage message to stderr, then exits.
-i file: Use the specified INI file instead of the default file.
-s: Suppresses all startup actions defined in the INI files.
-v: Prints version information to stderr, then exits.

USAGE

This section lists the default keyboard and mouse mappings to actions in a4. Everything is user-defined and may be customized to the user's liking (see CUSTOMIZATION below).

Keyboard commands

Ctrl-g c: Create a new terminal window.
Ctrl-g x x: Force close the focused terminal.
Ctrl-g Enter: Zoom the focused terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1.
Ctrl-g .: Minimize/unminimize the focused terminal window.
Ctrl-g q q: Force close all terminals and exit a4.
Ctrl-g Ctrl-l: Redraw the entire application.
Ctrl-g s: Enable or disable the status bar.
Ctrl-g S: Switch the position of the status bar between top and bottom.
Ctrl-g v [1..n] or Ctrl-g [F1..Fn]": View all terminal windows of only the tag at position n.
Ctrl-g t [1..n]: Set the focused terminal window to only the tag at position n.
Ctrl-g V [1..n]: Toggle viewing of terminal windows of the tag at position n.
Ctrl-g T [1..n]: Toggle on/off the tag at position n on the focused terminal window.
Ctrl-g v 0: View all terminal windows of all tags.
Ctrl-g v Tab: Switch to viewing the terminal windows of the previously selected set of tags.
Ctrl-g t 0: Set all tags on the focused terminal window.
Ctrl-g [1..n]: Focus terminal window number n.
Ctrl-g j: Focus next terminal window.
Ctrl-g k: Focus previous terminal window.
Ctrl-g Tab: Focus the last selected terminal window.
Ctrl-g H: Focus terminal window to the left.
Ctrl-g J: Focus terminal window below.
Ctrl-g K: Focus terminal window above.
Ctrl-g L: Focus terminal window to the right.
Ctrl-g 0: Toggle all visible terminal windows to be grouped for simultaneous typing. Minimized and read-only windows are not be typed into, even if they are included in the focused group.
Ctrl-g ): Toggle the focused terminal window to be part of a group of one or more focused windows for simultaneous typing. Minimized and read-only windows are not be typed into, even if they are included in the focused group.
Ctrl-g *: Toggle read-only status of the focused terminal window so that no keypresses are sent to it.
Ctrl-a f: Set layout to full screen.
Ctrl-a g: Set layout to grid.
Ctrl-a h: Set layout to zoom left.
Ctrl-a j: Set layout to zoom bottom.
Ctrl-a k: Set layout to zoom top.
Ctrl-a l: Set layout to zoom right.
Ctrl-a c: Set layout to columns.
Ctrl-a r: Set layout to rows.
Ctrl-a Space: Cycle forward through the layouts.
Ctrl-a Ctrl-Space: Cycle backward through the layouts.
Ctrl-a Tab: Switch to the previous layout.
Ctrl-a i: Increment the number of terminal windows in the zoom area.
Ctrl-a d: Decrement the number of terminal windows in the zoom area, if using a zoom layout.
Ctrl-a I: Increase the size of the zoom area by 5%, if using a zoom layout.
Ctrl-a D: Decrease the size of the zoom area by 5%, if using a zoom layout.
Shift-PageUp/PageDown: Scroll backward/forward half a screen in the focused terminal window.
Ctrl-g PageUp/PageDown: Scroll backward/forward a full screen in the focused terminal window.

Mouse in terminal window

Button1 click: Focus the selected terminal window.
Ctrl-Button1 click: Zoom the selected terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1.
Button3 click: Toggle the selected terminal window to be part of a group of one or more focused windows for simultaneous typing. Minimized and read-only windows are not be typed into, even if they are included in the focused group.
Ctrl-Button3 click: Toggle all visible terminal windows to be grouped for simultaneous typing. Minimized and read-only windows not be typed into, even if they are included in the focused group.
ScrollWheel up/down: Scroll backward/forward three lines in the terminal window that the mouse is hovering over.
Shift-ScrollWheel up/down: Scroll backward/forward half a screen in the terminal window that the mouse is hovering over.
Ctrl-ScrollWheel up/down: Scroll backward/forward a full screen in the terminal window that the mouse is hovering over.

Mouse in title bar

Button1 click: Minimize/unminimize the selected terminal window.
Button3 click: Toggle read-only status of the selected terminal window so that no keypresses are sent to it.

Mouse on tags in status bar

Button1 click: View terminal windows of only the selected tag.
Ctrl-Button1 click: Toggle viewing of selected tag terminal windows.
Button3 click: Set the focused terminal window to only the selected tag.
Ctrl-Button3 click: Toggle on/off the selected tag on the focused terminal window.

Mouse on layout symbol in status bar

Button1 click: Cycle forward through the layouts.
Button3 click: Cycle backward through the layouts.
Ctrl-Button1 click: Increment the number of terminal windows in the zoom area, if using a zoom layout.
Ctrl-Button3 click: Decrement the number of terminal windows in the zoom area, if using a zoom layout.
M-Ctrl-Button1 click: Increase the size of the zoom area by 5%, if using a zoom layout.
M-Ctrl-Button3 click: Decrease the size of the zoom area by 5%, if using a zoom layout.

Mouse on status bar text

Button1 click: Cycle to next status bar command, or refresh the status bar command if there is only one.

Mouse on layout frame line

Button1 click: Set layout to fullscreen.

CUSTOMIZATION

The configuration of a4 is controlled by settings in the a4.ini file. Review comments in the default system a4.ini file for instructions on how to customize these settings. See FILES below for the location of configuration files. A typical user configuration file is located at $HOME/.config/a4/a4.ini. The first line is often include = /usr/local/share/a4/a4.ini and then the following lines are the user's preferred override settings. Several configuration settings may be cleared out and reset by setting them equal to blank, including "startup =" and "statusbar_cmd =". Having a section head [ColorScheme] followed by a line with just a single = character clears out all previously defined ColorSchemes. Likewise, a section head [ColorRules] followed by a line with just a single = character clears out all previously defined ColorRules. Any Key/Mouse Combination assigned in any of the Action sections may be cancelled by assigning it to blank, e.g. C-g c =.LaterKey/MouseCombinationassignmentsoverrideearlierones.

ColorSchemes

Having different terminal color schemes dynamically applied helps to identify and keep track of all the different terminals with which you're working. The first step is to have different color schemes defined for use by the ColorRules later. Terminals typically have a default foreground (fg) color, background (bg) color, and 16 standard colors that are used by terminal applications. They can also define color numbers up to 255, but the are used less often. In a4, you can define ColorSchemes that are then applied to terminal windows dynamically by comparing the terminal's title text to defined ColorRules (see below). The first defined ColorScheme is used by default for all windows.

ColorRules

ColorRules look at the text in a terminal's title bar in order to dynamically set the terminal window's ColorScheme. This helps to identify and keep track of all the different terminals with which you're working. Color rules pair text with ColorSchemes. The text in a terminal window's title bar is compared with the text of each ColorRule, in the order specified, until one matches, and then that ColorScheme is applied to the terminal window. If none of the rules match, then the first ColorScheme defined in a4.ini is used.

The text of the title bar can be set using an echo command, for example echo -ne "\e]0;foobar\a" sets the title text to foobar. If using the bash shell, it is convenient to set the PROMPT_COMMAND environment variable to keep this text up-to-date with the current username, hostname, and present working directory. This is typically done with something like this in the user's .bashrc file: PROMPT_COMMAND='echo -ne "\e]0;$USER@$HOSTNAME:${PWD/$HOME/\~}\a"' With this kind of setup, it is then easy to specify ColorRules to have your terminals dynamically change colors based on these variables.

Terminology

Minimized and read-only terminal windows are never typed into, even if they are selected or focused.

selected: refers to just the one terminal window that has the cursor.
focus group: refers to the set of all visible terminal windows that have the group attribute enabled.
focused: refers to the selected terminal window, and if that window is part of the focus group then focused refers to all windows in the focus group.
mouse-selected: refers to just the one terminal window that is clicked on in the MouseTermwinActions or MouseTitlebarActions area.
mouse-focused: refers to the mouse-selected terminal window, and if that window is part of the focus group then mouse-focused refers to all windows in the focus group.

Actions that can be mapped to keyboard and mouse events

create: Create a new terminal window and is assigned the currently selected tags. The new window is placed in the #1 position in the order of all visible windows.
destroy: Force close the selected or mouse-selected terminal (not all focused or mouse-focused terminals).
focus[1-9|#|next|NEXT|prev|PREV|left|right|up|down|swap|group|groupall|0]: Move focus to the numbered terminal window specified by the numeral parameter 1-9. When # is used in the mapping instead of a numeral, the mapping is automatically expanded to nine separate mappings with the # character on both sides of the assignment replaced by the numerals 1-9. Parameters next and prev move focus to the next/prev numbered window in the ordered stack of all visible windows. Parameters NEXT and PREV do the same but skip over all minimized windows. Parameters left, right, up, and down move focus based on direction rather than number order. In the MouseTermwinActions or MouseTitlebarActions sections, mapping focus without any parameter focuses the mouse-selected window. Parameter swap focuses whichever was the previously focused window. Parameter group toggles the selected or mouse-selected window to be part of the focus group for simultaneous typing, while the groupall or 0 parameter toggles all visible windows to be part of the focus group.
keysequence char...: Send a sequence of characters to the focused terminal window. There is a set of backslash character escape sequences that may be used with this: \a for alert, \b for backspace, \e for escape, \f for form feed, \n for newline, \r for carriage return, \t for horizontal tab, \v for vertical tab, and \\ for backslash.
layout <layout name>|[+]1|-1|swap: Set layout to one of the eight named layouts: zoom_left, zoom_right, zoom_top, zoom_bottom, fullscreen, grid, rows, and columns. Parameter 1 or +1, cycles forward through the layouts, and -1, cycles backward. Parameter swap sets the layout to whatever was previously set.
minimize: Minimize/unminimize the selected or mouse-selected terminal window.
quit: Force close all terminals and exit a4.
readonly: Toggle read-only status of the selected or mouse-selected terminal window so that no keypresses are sent to it.
redraw: Redraw the entire application.
scrollback [<n lines>|<.n percent>]: Scroll the focused or mouse-focused terminal window(s). Positive numbers scroll backward and negative numbers scroll forward. Integer numbers specify the exact number of lines to scroll. Numbers with a decimal point are interpreted as a percentage of a full screen of lines to scroll, e.g. .5 scrolls back half a screen's worth of lines.
statusbar next|vis|on|off|pos|top|bottom: Parameter next reruns the statusbar command, or cycles to run the next statusbar command if there are more than one. Parameter vis toggles the status bar on and off, or on and off set the visibility directly. Parameter pos toggles the statusbar position between top and bottom, or top and bottom set the position directly.
tag [<tag name>|_all]: Set the selected or mouse-selected terminal window to have only the specified tag name tag enabled. Special parameter _all sets the window to have all tags enabled on it. If mapped in the MouseTagNamesActions section, tag may be used without a parameter to set the selected window to have only the clicked tag enabled.
tagtoggle [<tag name>]: Toggle the tag name tag on and off on the selected or mouse-selected terminal window. If mapped in the MouseTagNamesActions section, tagtoggle may be used without a parameter to toggle the clicked tag on the selected window.
view [<tag name>|_all|_swap]: View all terminal windows with the tag name tag enabled. Special parameter _all views all windows of all tags. Special parameter _swap views the windows of whichever set of tags were previously selected. If mapped in the MouseTagNamesActions section, view may be used without a parameter to view all windows of the clicked tag.
viewtoggle [<tag name>]: Toggle viewing terminal windows of the tag name specified. If mapped in the MouseTagNamesActions section, viewtoggle may be used without a parameter to toggle viewing windows of the clicked tag.
zoom [n]: Zoom the selected or mouse-selected terminal window to the top of the window stack, to be window #1, or swap with the next window if it is already #1. If a parameter n is passed then that window number is zoomed instead of the selected window.
zoomnum [[+|-]n]: If the parameter passed includes a + or - sign symbol prefix then the action is to increase or decrease the number of terminal windows in the zoom area by n. If there is no sign symbol then the number of windows in the zoom area is set to n. If no parameter is passed then the number of windows in the zoom area is reset to the definition in the a4.ini configuration file. The minimum value of zoomnum is 1.
zoomsize [[+|-].n]: If the parameter passed includes a + or - sign symbol prefix then the action is to increase or decrease the size of the zoom area by n percent of the screen. If there is no sign symbol then the size of the zoom area is set to n percent of the screen. If no parameter is passed then the size of the zoom area is reset to the definition in the a4.ini configuration file. The minimum value of zoomsize is .1 and the maximum value is .9..

ENVIRONMENT

A4: All processes running within a4 have this variable set to the version.
TERM: In general, just use whatever the underlying terminal defaults to for this variable. If there's any question, use xterm-256color.
COLORTERM: If you're not seeing 24-bit truecolor, set this variable to 24bit or truecolor in the underlying terminal and restart a4.

FILES

a4.ini: is the configuration file read by a4 during initial startup. The location of the user's default file is $XDG_CONFIG_HOME/a4/a4.ini, which is usually $HOME/.config/a4/a4.ini and the system default file is /usr/local/share/a4/a4.ini.
*.ini: There are additional, partial configuration files provided in the /usr/local/share/a4/ directory, which may be included in a user's own a4.ini file. For example, theme_default.ini includes all the a4 color theme settings; cs_solarized.ini defines the Solarized terminal color schemes, which may be used in color rules; vt220.ini defines the vt220 ANSI escape codes for terminal overrides.

NOTES

It is useful to run a4 with abduco(1) so that you can disconnect and reconnect while your a4 session continues to run in the background. This is also helpful if you run a4 on remote machines since the session continues to run even if your connection to the machine is lost, and you can reconnect later without losing any of your work. Consider setting a alias such as alias a4.abduco="abduco -A a4 a4 $@".

There's a configuration error in the xterm-256color file installed by some Linux distros that causes the mouse to behave incorrectly by printing characters to the terminal. If you experience this problem, run the following command to put a local, patched copy of the file in place for your login account: infocmp xterm-256color | sed -E 's/(kmous=\\E\[)</\1M/' | tic -o ~/.terminfo -

More documentation of a4 can be found at https://a4term.com/