QMAN(1)

📦
version 1.5.1 · 2 versions
, in alpine 3.24, nixpkgs unstable

🌸 QMAN(1) 💅

Bestie, welcome to the qman page from the General Commands Manual — she’s giving modern manual viewer, and we’re obsessed. 🫶

✨ NAME ✨

Qman — A more modern manual page viewer for our terminals 💖

🦋 SYNOPSIS 🦋

qman [options]
qman [options] -n
qman [options] [[section] page]
qman [options] -k regexp ...
qman [options] -f page ...

🌈 DESCRIPTION 🌈

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

🍓 EXAMPLES 🍓

  • qman or qman -n — Show the index (home) page, a collection of all manual pages available on the system.
  • qman ls — Show the manual page for ls.
  • qman 1 ls or qman `ls(1)' — Show the manual page for ls from manual section 1.
  • qman -f open — Show all manual pages named open across all sections (whatis).
  • qman -k open — Show all manual pages whose short description matches the term open (apropos).

🎀 USER INTERFACE 🎀

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 — but make it a glow-up list, because we’re not doing tables today:

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

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

🐭 MOUSE SUPPORT 🐭

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. ✨

NOTE 1 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).
NOTE 2 Some terminals may report mouse cursor position inaccurately, causing difficulties with clicking and dragging.

🔥 OPTIONS 🔥

The program accepts the following non-argument options:

  • -n, --index — 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.)
  • -k, --apropos regexp ... — 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.
  • -f, --whatis page ... — Interactive equivalent to whatis(1). Display the name, section, and short description of each of the manual page argument.
  • -l, --local-file file ... — 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.
  • -K, --global-apropos regexp ... — 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.
  • -a, --all page ... — 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.
  • -T, --cli — 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.
  • -z, --cli-force-color — 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.
  • -A, --action action_name — Automatically perform program action action_name upon startup. The list of valid action names can be found under USER INTERFACE.
  • -C, --config-path file — Use file as the configuration file for Qman.
  • -v, --version — Print program version and exit.
  • -h, --help — Print a help message and exit.

🌸 CONFIGURATION 🌸

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:

Section [chars]

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

  • 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. 🧚

Okay so real talk: the default values for this section were hand-picked so Qman behaves correctly on basically every terminal ever, including the venerable xterm(1) and the Linux console, and with all fonts. 💖 Depending on what your terminal can do, Qman may decide to revert to those defaults and straight-up ignore any options you specified in this section. No cap. You can override that by adding unicode=true to the [tcap] section. ✨

🎨 Section [colours] 🎨

These options set the user interface colors. Pick a color, any color 💅

  • 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.

⌨️ Section [keys] ⌨️

These options specify which keys are mapped to each program action. Main character energy for your keyboard 🔥

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, such 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.

🖱️ Section [mouse] 🖱️

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

  • enable (boolean, default false) — Enables mouse support
  • left_handed (boolean, default false) — Swaps the left and right mouse buttons
  • left_click_open (boolean, default false) — Causes the left mouse button to invoke the OPEN action and/or act as the ENTER key

🪟 Section [layout] 🪟

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

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

🛰️ Section [tcap] 🛰️

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

  • colours (int, default -1) — Number of colors supported by the terminal, or -1 to auto-detect
  • rgb (ternary, default auto) — True if terminal can re-define colors, false if not, auto to auto-detect
  • unicode (ternary, default auto) — True if terminal supports Unicode, false if not, auto to auto-detect
  • clipboard (ternary, default auto) — True if terminal supports clipboard operations (OSC 52), false if not, auto to auto-detect
  • escdelay (int, default 60) — Number of milliseconds to wait after receiving 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. 💀

🧰 Section [capabilities] 🧰

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

  • sections_on_top (boolean, default true) — Show a list of (links to the page’s) sections at the top of each page
  • http_links (boolean, default true) — Generate hyperlinks to HTTP URLs
  • email_links (boolean, default true) — Generate hyperlinks to email addresses
  • file_links (boolean, default true) — Generate hyperlinks to local files and directories
  • hyphenate (boolean, default true) — Hyphenate long words in manual pages
  • justify (boolean, default true) — Justify text in manual pages
  • icase_search (boolean, default true) — Ignore case when performing page text search
  • sp_substrings (boolean, default 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.

🧚 Section [misc] 🧚

This section contains various miscellaneous options:

  • system_type — string, default mandb — the manual system type
  • man_path — string, default /usr/bin/man — path to the man(1) command
  • groff_path — string, default /usr/bin/groff — path to the groff(1) command
  • whatis_path — string, default /usr/bin/whatis — path to the whatis(1) command
  • apropos_path — string, default /usr/bin/apropos — path to the apropos(1) command
  • browser_path — string, default /usr/bin/xdg-open — path to the command used to open HTTP links (i.e. your web browser)
  • mailer_path — string, default /usr/bin/xdg-email — path to the command used to open e-mail links (i.e. your e-mail software)
  • viewer_path — string, default /usr/bin/xdg-open — path to the command used to open links to files in the local filesystem
  • reset_after_http — boolean, default true — re-initialize curses after opening an http(s) link
  • reset_after_email — boolean, default true — re-initialize curses after opening an e-mail link
  • reset_after_viewer — boolean, default true — re-initialize curses after opening a link to a local filesystem file
  • terminfo_reset — boolean, default false — reset the terminal using the strings provided by terminfo(5) on shutdown
  • history_size — unsigned int, default 256k — maximum number of history entries

system_type has to match the Unix manual system your O/S is actually running, bestie. No vibes-based guessing 💅

  • mandb — most Linux distributions
  • mandoc — Void Linux, Haiku, others?
  • freebsd — FreeBSD
  • darwin — macOS

To dodge that annoying screen redraw 😭, you can set reset_after_http, reset_after_email, or reset_after_viewer to false whenever browser_path, mailer_path, or viewer_path respectively point to a GUI program. GUI = no terminal to restore, so the reset is just extra drama 🎭

Setting terminfo_reset to true kicks off a full terminal reset on program shutdown, using the strings provided by terminfo(5). Why would you want this? Because if your ncurses implementation doesn't completely restore terminal settings (e.g. colors) on exit, this is the fix. But — side effect alert 🚨 — it also clears the screen and erases your scroll history. So like, pick your fighter.

When you're on a horizontally narrow terminal, setting hyphenate to true and/or justify to false can genuinely improve the program's output. Narrow terminal + full justification = chaos, ngl 🌸

Setting sp_substrings to false makes incremental search results only include pages whose names start with the user's input. Setting it to true (which is the default, ikyk) also includes pages whose names contain the input as a substring — provided there's enough space left in the window. Space said no? Then it's a no 🫶

🎀 Include directive

You can pull in supplemental config files, like so:

include path

Where path is either an absolute path to the supplemental file, or a path relative to the directory component of the configuration file that's doing the including. So yes, relative paths are relative to the includer, not to you, not to your shell, not to your heart 💖

🦋 Notes on syntax

Include paths and option values may optionally be placed inside single or double quotes. They can also contain these 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 counts as a comment and gets yeeted. Discarded. Gone. Periodt 🗑️✨

🌈 ENVIRONMENT 🌈

Bestie, take care setting your TERM environment variable so it actually matches your virtual terminal. Mismatch = regrets 💀

When the program is invoked using -T, it tries to set its page width to the value of the MANWIDTH environment variable. If MANWIDTH hasn't been set, it tries to set the page width to the value of COLUMNS. And if that fails too, it tries to auto-detect the terminal's size using an ioctl(2) — and if that also fails? It just sets it to the default value of 80. Iconic fallback behaviour honestly 👑

💅 SIGNALS 💅

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

This feature is handy for people who want to automatically switch themes depending on the time of day — day mode, night mode, main character energy 🌞🌙

Heads up though: it's noted as experimental, and it has issues with certain terminals. So cute in theory, slightly cursed in practice 🙈

⭐ EXIT STATUS ⭐

  • 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). Same family, same energy 💜

🫶 SEE ALSO 🫶

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

👑 AUTHOR 👑

Written by Pantelis Panayiotou / plp13 on GitHub 🎀

🙈 BUGS 🙈

Please report bugs at https://github.com/plp13/qman/issues — the maintainer wants to hear from you, fr fr 🐛💌

And that's the whole page, bestie!! You made it to the very end, I'm so proud 🥹💖 This was Qman 1.5.1, dated December 15, 2023 — that's the source/version and date right there, so you never have to wonder which build you're reading about. Now go read some manual pages, slay, and remember: the man page is your friend 🌸✨🦋

📦 where this page comes from