A more modern manual page viewer for our terminals
Version 1.3.0 -- see what's new
Index page:
Opening a manual page:
Viewing a manual page:
Using the table of contents:
Searching incrementally:
Performing apropos:
Online help:
Linux manual pages are lovely. They are concise, well-written, complete, and downright useful. However, the standard way of accessing them from the command-line hasn't changed since the early days.
Qman aims to change that. It's a modern, full-featured manual page viewer featuring hyperlinks, web browser like navigation, a table of contents for each page, incremental search, on-line help, and more. It also strives to be fast and tiny, so that it can be used everywhere. For this reason, it's been written in plain C and has only minimal dependencies.
- Index page that displays all manual pages available on the system, sorted alphabetically and organised by section
- Pages for apropos and whatis results
- Hyperlinks to other manual pages
- Hyperlinks for URLs and email addresses (handled with xdg-open by default)
- In-page hyperlinks
- A table of contents for each manual page
- Incremental search for manual pages
- Incremental free page text search
- Command-line options similar to those of
man(most importantly,-kand-f) - Keyboard mappings similar to those of
less - Mouse support
- Navigation history
- On-line help
- Fully configurable using an INI-style config file
- Manual page
All basic functionality has been completed. The software has been in use for over a year now, and should considered stable. Bugs may still arise, of course, and should be reported using the issues page.
- Improved navigation using the table of contents
- Support for manual pages compressed using Bzip2
- Support for
groff's legacy typewriter sequences (GROFF_NO_SGR) - Support for embedded HTTP links (for example,
named(8)uses these to provide links to several RFC documents) - New light RGB theme catppuccin_latte.conf
- Automated versioning
- Installation instructions for different distributions have been brought up to date and moved to PACKAGING.md
- Miscellaneous bug fixes and documentation enhancements
💡 Note
Users using custom config files might need to update them when a new version version of Qman comes out. Please refer to the manual page, modernity.conf and modernity_gui.conf for more info.
Clone the main branch, which contains Qman's latest stable version:
$ git clone -b main https://github.com/plp13/qman qman
Tagged releases with tarballs are also available, starting with version 1.2.1.
Qman is written in plain C, and thus requires a compiler such as gcc or
clang. Its only required library dependencies are glibc, ncurses, hinit,
and zlib. It uses the meson build system.
There is also an optional library dependency:
bzip2-- support for manual pages compressed withbzip2
Note that Qman is a front-end to GNU man, and therefore requires man and
groff to be installed. In order for it to make sense, a Unix manual pages
database must also be present.
Make sure all of the above dependencies are installed, and do the following:
$ meson setup build/
$ cd build/
$ meson compile
$ sudo meson install
💡 Note
If using an older version of
meson, you may need to substitute the aforementionedmeson compilecommand withninja
For Arch Linux users, there is a an AUR package.
Prospective packagers should take a look at PACKAGING.md, which provides help for building the program on various Linux distributions.
Always make sure you are up-to-date with the main branch. And, of course,
RTFM:
$ qman qman
❓ What is the location of the configuration file?
~/.config/qman.conf (user-specific) or /etc/xdg/qman.conf (system-wide).
❓ Calling
qmanwithout any parameters fails with messageApropos '': nothing appropriate
Your system does not have a manual page index cache. This can be fixed by running (as root):
# mandb
❓ I have enabled mouse support by adding
enable=trueto the[mouse]section of my configuration file, but now I'm unable to copy text to the clipboard using the mouse, and/or my mouse behaves erratically
Mouse support is experimental, and depends on features that are not fully implemented by all terminals. See Qman's manual page for more information.
❓ Trying to open an HTTP or e-mail link causes the program to terminate (or does nothing)
By default, Qman uses xdg-open to open such links. On desktop Linux systems,
this is sufficient to open them using the default browser / email client. On
other systems, you may need to specify alternative programs with the
browser_path and mailer_path options in the misc section of Qman's
configuration file. To avoid opening such links altogether, set both options to
a command that does nothing, e.g. /usr/bin/false.
❓ Qman does not look as pretty on my system as in the screenshots
That look can be achieved by using one of the supplied modernity.conf and modernity_gui.conf configuration files. Both files require a modern virtual terminal with support for Unicode fonts and 256 colors.
If you wish to contribute to the program's development, clone the devel branch:
$ git clone -b devel https://github.com/plp13/qman qman
You should also take a look at TESTING.md, which describes the procedures and tools we use for testing.