FreeBSD Manual Pages
QMAN(1) General Commands Manual QMAN(1) 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. 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. 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 fa- cilities 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 as- sociated keyboard mappings: Action name Description Key mappings ----------------------------------------------------------------------------- UP Scroll up one line and/or focus on UP, y, k the previous link DOWN Scroll down one line and/or focus on DOWN, e, j the next link 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 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, in- voking 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 CON- FIGURATION. 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 sup- ported 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 be- havior 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 descrip- tions. -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 ig- nored. -T, --cli Suppress the text user interface and output directly to the ter- minal. This option can be used to redirect the program's for- matted 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 INTER- FACE. -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 <https://specifica- tions.freedesktop.org/basedir-spec/latest/>. 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 <https://en.wikipedia.org/wiki/INI_file>, extended with an include di- rective to allow for the configuration to be spread across multiple files. Different configuration options are grouped into sections. The para- graphs 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: 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 sec- tions 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 char- acter. 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 behav- ior can be overridden by adding unicode=true to the [tcap] section. Section [colours] 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 be- tween 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 capabili- ties, Qman may choose to revert to said defaults, and ignore any op- tions you have specified in this section. This behavior can be over- ridden by adding colors=256 and/or rgb=true to the [tcap] section. Section [keys] 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 BACK- SPACE requires specifying both KEY_BACKSPACE and BS. Section [mouse] This section contains the following options that pertain to mouse sup- port: Option Type Def. value Description -------------------------------------------------------------------------------------- enable boolean false Enables mouse support left_handed boolean false Swaps the left and right mouse but- tons left_click_open boolean false Causes the left mouse button to in- voke 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: Option Type Def. value Description -------------------------------------------------------------------------------- sbar boolean true Indicates whether the scrollbar will be displayed beep boolean true Indicates whether to beep the termi- nal 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) Section [tcap] Normally, Qman detects the terminal's capabilities automatically. Op- tions 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 col- ors, false if not, auto to auto-de- tect 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 be- fore interpreting it as the escape key. Users with historical termi- nals or very unreliable network con- nections may want to increase this. Beware that Qman uses these capabilities to decide whether to either honor or ignore various configuration options specified elsewhere, par- ticularly in the [chars] and [colours] sections mentioned above. Auto-detection should work correctly in most cases; it's therefore rec- ommended 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: Option Type Def. value Description -------------------------------------------------------------------------------- sec- boolean true Show a list of (links to the tions_on_top 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 ad- dresses 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 fea- tures. Also, disabling hyphenate and/or justify can improve legibility in narrow terminal windows. Section [misc] 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/apro- Path to the apropos(1) command pos 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_af- boolean true Re-initialize curses after open- ter_http ing an http(s) link reset_af- boolean true Re-initialize curses after open- ter_email ing an e-mail link reset_af- boolean true Re-initialize curses after open- ter_viewer ing a link to a local filesystem file terminfo_re- boolean false Reset the terminal using the set 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: • mandb <https://gitlab.com/man-db/man-db> - most Linux distributions • mandoc <https://mandoc.bsd.lv/> - Void Linux, Haiku, others? • freebsd <https://www.freebsd.org/> - FreeBSD • darwin <https://www.apple.com/macos/> - macOS To avoid an annoying screen redraw, options reset_after_http, reset_af- ter_email, or reset_after_viewer can be set to false whenever browser_path, mailer_path, or viewer_path point to a GUI program re- spectively. Setting terminfo_reset to true will initiate a full terminal reset, us- ing the strings provided by terminfo(5), upon program shutdown. This may be necessary if your ncurses implementation doesn't completely re- store 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 win- dow. Include directive 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 per- forms the inclusion. Notes on syntax Include paths and option values may optionally be placed inside single or double quotes. They can also include the following escape se- quences: • \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 com- ment and is discarded. ENVIRONMENT 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. SIGNALS Upon receiving SIGUSR1, the program interrupts its operation and at- tempts 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 ex- perimental and has issues with certain terminals. EXIT STATUS 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). 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 Qman 1.5.0 December 15, 2023 QMAN(1)
NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | USER INTERFACE | MOUSE SUPPORT | OPTIONS | CONFIGURATION | ENVIRONMENT | SIGNALS | EXIT STATUS | SEE ALSO | AUTHOR | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=qman&sektion=1&manpath=FreeBSD+Ports+15.0>