GSP
Quick Navigator
Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
* Sign Up! *

Support
Customer Portal
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
QMAN(1) General Commands Manual QMAN(1)

Qman - A more modern manual page viewer for our terminals

qman [options]

qman [options] -n

qman [options] [[section] page]

qman [options] -k regexp ...

qman [options] -f page ...

Qman is a modern, interactive manual page viewer for our terminals. It strives to be easy to use for anyone familiar with the man(1) command, and also to be fast and tiny, so that it can be used everywhere.

Show the index (home) page, a collection of all manual pages available on the system
Show the manual page for ls
Show the manual page for ls from manual section 1
Show all manual pages named open across all sections (whatis)
Show all manual pages whose short description matches the term open (apropos)

Qman’s reactions to user input are similar to what one would expect from a pager such as less(1), or from an ncurses-based browser such as links(1). Manual, apropos, and whatis pages are adorned with links to other pages, HTTP locations, e-mail addresses, files in the local filesystem, or (sub)sections within the current page. These links can be selected and opened.

The program provides a scrollbar, a status line, incremental search facilities for locating manual pages, and facilities for searching through the text of the page currently being displayed. A table of contents is generated for each page, allowing for easy navigation to its sections, sub-sections, and paragraphs. Navigation history and on-line help are also available.

The table below summarizes the program’s actions and their default associated keyboard mappings:

Action name Description Key mappings
UP Scroll up one line and/or focus on the previous link UP, y, k
DOWN Scroll down one line and/or focus on the next link DOWN, e, j
LEFT Scroll left one tab stop LEFT, <
RIGHT Scroll right one tab stop RIGHT, >
PGUP Scroll up one page PGUP, b
PGDN Scroll down one page PGDN, f
HOME Go to page top HOME, g
END Go to page bottom END, G
OPEN Open focused link ENTER, o
OPEN_APROPOS Perform apropos on focused link a
OPEN_WHATIS Perform whatis on focused link w
SP_OPEN Open a manual page using a dialog O
SP_APROPOS Perform apropos using a dialog A
SP_WHATIS Perform whatis using a dialog W
INDEX Go to index (home) page i, I
BACK Go back one step in history BACKSPACE, [
FWRD Go forward one step in history ]
HISTORY Show history menu s, S
TOC Show table of contents t, T
SEARCH Forward search in current page text /
SEARCH_BACK Backward search in current page text ?
SEARCH_NEXT Go to next search result n
SEARCH_PREV Go to previous search result N
HELP Show the help dialog h, H
QUIT Exit the program q, Q

All of the aforementioned keyboard mappings are customizable. For more information, see CONFIGURATION.

Mouse input is supported but is considered experimental and is disabled by default. The CONFIGURATION section contains instructions on how to enable it. Many terminal emulators still provide basic mouse support when mouse input is disabled.

When mouse input is enabled:

  • The scroll wheel can be used as an alternative way for scrolling, invoking the UP and DOWN program actions
  • Pressing and dragging the left mouse button over page text causes it to be selected and copied to the clipboard (see NOTES 1 & 2)
  • Pressing and dragging the left mouse button over the scrollbar allows for scrolling through the page (see NOTE 2)
  • Clicking the left mouse button on a link causes the link under the cursor to be selected (see NOTE 2)
  • Clicking the middle button (the scroll wheel for most mice) invokes the OPEN action, opening the currently selected link
  • Clicking the right button invokes the HELP action
  • When inputting a search query or selecting from a menu, the middle button acts as a substitute for the ENTER key, and the right button as a substitute for CTRL-C
  • When selecting from a menu, clicking the left button causes the menu entry under the cursor to be selected

The above behavior can be customized. For more information, see CONFIGURATION.

There is no reliable method for terminal clients to copy data to the clipboard. An escape code (OSC 52) does exist but is supported reliably only by kitty(1) and ghostty(1). For all other terminals, Qman will default to using commands such as xclip(1), wl-clipboard(1), or pbcopy(1). However, these will only work when running locally and within a desktop environment (not when using SSH).
Some terminals may report mouse cursor position inaccurately, causing difficulties with clicking and dragging.

The program accepts the following non-argument options:

Show a list of all manual pages on the system, together with their sections and short descriptions. (This is the default behavior when the program is launched with no command-line options and no arguments.)
Interactive equivalent to apropos(1). Search for manual pages whose names and/or short descriptions match any of the regexp arguments, and display their names, sections, and short descriptions.
Interactive equivalent to whatis(1). Display the name, section, and short description of each of the manual page argument.
Activate “local” mode. Format and display each local manual file, rather than searching through the system’s manual pages. Each file is interpreted as the nroff source file of a manual page.
Show the contents of all manual pages whose names and/or short descriptions match any of the regexp arguments. Beware that this option might cause long execution times. If not used in conjunction with -T, it is ignored.
Show the contents of all manual pages whose names match any of the page arguments. Beware that this option might cause long execution times. If not used in conjunction with -T, it is ignored.
Suppress the text user interface and output directly to the terminal. This option can be used to redirect the program’s formatted output to a text file or to another command.
Produce colorful output using terminal escape codes, even when not running inside a terminal. This must be used in conjunction with -T and otherwise will be ignored.
Automatically perform program action action_name upon startup. The list of valid action names can be found under USER INTERFACE.
Use file as the configuration file for Qman.
Print program version and exit.
Print a help message and exit.

Qman expects to find its configuration file in the standard locations defined by the XDG Base Directory Specification. The following locations are searched in sequence:

  • Any file specified using -C or --config-path
  • ${XDG_CONFIG_HOME}/qman/qman.conf
  • ${HOME}/.config/qman/qman.conf
  • <path>/qman/qman.conf where <path> is an entry in ${XDG_CONFIG_DIRS}
  • <configdir>/qman.conf where <configdir> is a compile-time option
  • /etc/xdg/qman/qman.conf
  • /etc/qman/qman.conf

The process stops once a configuration file has been found.

Qman’s configuration file uses the basic INI file format, extended with an include directive to allow for the configuration to be spread across multiple files.

Different configuration options are grouped into sections. The paragraphs below summarize the sections and configuration options that are available:

Options in this section specify what characters will be used to draw the text user interface:

Option Description
sbar_top scrollbar top end
sbar_vline scrollbar track line
sbar_bottom scrollbar bottom end
sbar_block scrollbar knob
trans_mode_name transition between the mode and name sections of the status bar
trans_name_loc transition between the name and location sections of the status bar
trans_prompt_help transition between the prompt and help sections of the status bar
trans_prompt_em transition between the prompt and error message sections of the status bar
box_hline dialog box horizontal line
box_vline dialog box vertical line
box_tl dialog box top left corner
box_tr dialog box top right corner
box_bl dialog box bottom left corner
box_br dialog box bottom right corner
arrow_up up arrow
arrow_down down arrow
arrow_lr left/right arrow / equivalence sign

Each configuration option value must consist of a single Unicode character.

The default values for this section have been chosen to allow Qman to work correctly with virtually all terminals, including the venerable xterm(1) and the Linux console, and with all fonts. Depending on the terminal’s capabilities, Qman may choose to revert to said defaults, and ignore any options you have specified in this section. This behavior can be overridden by adding unicode=true to the [tcap] section.

Options in this section specify the user interface colors:

Option Description
text page text
search matched search terms in page text
link_man links to manual pages
link_man_f links to manual pages (focused)
link_http HTTP links
link_http_f HTTP links (focused)
link_email e-mail links
link_email_f e-mail links (focused)
link_file links to files in the local filesystem
link_file_f links to files in the local filesystem (focused)
link_ls in-page links
link_ls_f in-page links (focused)
sb_line scrollbar track line
sb_block scrollbar knob
stat_indic_mode status bar mode section
stat_indic_name status bar name section
stat_indic_loc status bar location section
stat_input_prompt status bar input prompt
stat_input_help status bar help section
stat_input_em status bar error message section
imm_border pop-up dialogs border
imm_title pop-up dialogs title
sp_input input dialog prompt
sp_text input dialog incremental search text
sp_text_f input dialog incremental search text (focused)
help_text help dialog entries text
help_text_f help dialog entries text (focused)
history_text history dialog entries text
history_text_f history dialog entries text (focused)
toc_text table of contents dialog entries text
toc_text_f table of contents dialog entries text (focused)

Each color is defined using three words separated by whitespace:

foreground background bold

foreground and background can be one of black, red, green, yellow, blue, magenta, cyan, or white. Alternatively, they can be a number between 0 and 255, or a hexadecimal RGB value using the #RRGGBB notation.

bold is a boolean that signifies whether the foreground color will have a high (true) or low (false) intensity.

The default values for this section have been chosen to allow Qman to work correctly with virtually all terminals, including the venerable xterm(1) and the Linux console. Depending on the terminal’s capabilities, Qman may choose to revert to said defaults, and ignore any options you have specified in this section. This behavior can be overridden by adding colors=256 and/or rgb=true to the [tcap] section.

Options in this section specify which keys are mapped to each program action.

The section contains 25 configuration options, each corresponding to one of the program actions described in the USER INTERFACE section of this manual page. Their value is a tuple of up to 8 key definitions, separated by whitespace:

key_1 key_2 key_3 key_4 key_5 key_6 key_7 key_8

The value of each key_i can take one of the following values:

  • Any character, surch as a, b, c, etc.
  • Any ncurses(3x) keycode, such as KEY_UP or KEY_HOME
  • F1 to F12 (for the function keys)
  • ESC (for the ESC key)
  • EXT (for CTRL-C)
  • LF (for the ENTER key)
  • BS (for the BACKSPACE key)
  • HT (for the TAB key)
  • SPACE (for the spacebar)

For reasons of compatibility with various terminals, mapping the ENTER key requires specifying both KEY_ENTER and LF. Similarly, mapping CTRL-C requires specifying both KEY_BREAK and ETX, and mapping BACKSPACE requires specifying both KEY_BACKSPACE and BS.

This section contains the following options that pertain to mouse support:

Option Type Def. value Description
enable boolean false Enables mouse support
left_handed boolean false Swaps the left and right mouse buttons
left_click_open boolean false Causes the left mouse button to invoke the OPEN action and/or act as the ENTER key

This section contains various options that concern the layout of the text user interface:

Option Type Def. value Description
sbar boolean true Indicates whether the scrollbar will be displayed
beep boolean true Indicates whether to beep the terminal on error
lmargin unsigned int 2 Size of margin between the left side of the screen, and the page text
rmargin unsigned int 2 Size of margin between the page text and the scroll bar and/or the right side of the screen
tabstop unsigned int 8 Number of characters in a tab stop (used by actions LEFT and RIGHT)

Normally, Qman detects the terminal’s capabilities automatically. Options in this section provide the ability to specify them explicitly, overriding this behavior:

Option Type Def. value Description
colours int -1 Number of colors supported by the terminal, or -1 to auto-detect
rgb ternary auto True if terminal can re-define colors, false if not, auto to auto-detect
unicode ternary auto True if terminal supports Unicode, false if not, auto to auto-detect
clipboard ternary auto True if terminal supports clipboard operations (OSC 52), false if not, auto to auto-detect
escdelay int 60 Number of miliseconds to wait after receving ESC from the keyboard before interpreting it as the escape key. Users with historical terminals or very unreliable network connections may want to increase this.

Beware that Qman uses these capabilities to decide whether to either honor or ignore various configuration options specified elsewhere, particularly in the [chars] and [colours] sections mentioned above. Auto-detection should work correctly in most cases; it’s therefore recommended to not modify any of the options in this section, except when discovering or reporting bugs.

This section allows the user to disable various non-essential features of Qman:

Option Type Def. value Description
sections_on_top boolean true Show a list of (links to the page’s) sections at the top of each page
http_links boolean true Generate hyperlinks to HTTP URLs
email_links boolean true Generate hyperlinks to email addresses
file_links boolean true Generate hyperlinks to local files and directories
hyphenate boolean true Hyphenate long words in manual pages
justify boolean true Justify text in manual pages
icase_search boolean true Ignore case when performing page text search
sp_substrings boolean true Include substring matches when performing incremental search of manual pages

All features are enabled by default.

On slow machines, performance can be improved by disabling some features. Also, disabling hyphenate and/or justify can improve legibility in narrow terminal windows.

This section contains various miscellaneous options:

Option Type Def. value Description
system_type string mandb Manual system type
man_path string /usr/bin/man Path to the man(1) command
groff_path string /usr/bin/groff Path to the groff(1) command
whatis_path string /usr/bin/whatis Path to the whatis(1) command
apropos_path string /usr/bin/apropos Path to the apropos(1) command
browser_path string /usr/bin/xdg-open Path to the command that will be used to open HTTP links (i.e. your web browser)
mailer_path string /usr/bin/xdg-email Path to the command that will be used to open e-mail links (i.e. your e-mail software)
viewer_path string /usr/bin/xdg-open Path to the command that will be used to open links to files in the local filesystem
reset_after_http boolean true Re-initialize curses after opening an http(s) link
reset_after_email boolean true Re-initialize curses after opening an e-mail link
reset_after_viewer boolean true Re-initialize curses after opening a link to a local filesystem file
terminfo_reset boolean false Reset the terminal using the strings provided by terminfo(5) on shutdown
history_size unsigned int 256k Maximum number of history entries

system_type must match the Unix manual system used by your O/S:

To avoid an annoying screen redraw, options reset_after_http, reset_after_email, or reset_after_viewer can be set to false whenever browser_path, mailer_path, or viewer_path point to a GUI program respectively.

Setting terminfo_reset to true will initiate a full terminal reset, using the strings provided by terminfo(5), upon program shutdown. This may be necessary if your ncurses implementation doesn’t completely restore terminal settings (e.g. colors) upon exit, but will also clear the screen and erase your scroll history as a side effect.

When using a horizontally narrow terminal, setting hyphenate to true and/or justify to false can improve the program’s output.

Setting sp_substrings to false causes incremental search results to only include pages whose names start with the user’s input. Setting it to true (the default) will also include pages whose names contain the input as a substring, provided there is enough space left in the window.

Supplemental configuration files can be included using:

include path

Where path is either an absolute path to the supplemental, or a path relative to the directory component of the configuration file that performs the inclusion.

Include paths and option values may optionally be placed inside single or double quotes. They can also include the following escape sequences:

  • \a, \b, \t, \n, \v, \f, and \r – interpreted according to the ASCII standard
  • \e – interpreted as an escape (0x1b) character
  • \\ – interpreted as a backslash
  • \’ and \“ – interpreted as a single and a double quote respectively

All text following a ; until the end of the line is considered a comment and is discarded.

Users should take care setting their TERM environment variable to match their virtual terminal.

When invoked using -T, the program tries to set its page width to the value of the MANWIDTH environment variable. If MANWIDTH hasn’t been set, it tries to set it to the value of COLUMNS. Failing that, it tries to auto-detect the terminal’s size using an ioctl(2) and, if that also fails, it sets it to the default value of 80.

Upon receiving SIGUSR1, the program interrupts its operation and attempts to re-parse its configuration file, using the process outlined in CONFIGURATION.

This feature can be useful for people who wish to automatically switch themes depending on the time of day. It should be noted that it is experimental and has issues with certain terminals.

Value Description
0 Successful program execution
1 Usage or syntax error
2 Operational error
3 A child process returned a non-zero exit status
4 Configuration file error
16 No manual page(s) found matching the user’s request

The above are similar to the exit values of man(1).

man(1), apropos(1), whatis(1), pinfo(1)

Written by Pantelis Panayiotou / plp13 on GitHub

Please report bugs at https://github.com/plp13/qman/issues

December 15, 2023 Qman 1.5.1
Search for    or go to Top of page |  Section 1 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.