A more modern manual page viewer for our terminals
Version 1.2.0 -- see what's new
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,-k
and-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.
- Fixed issue #6: hang on AArch64
- The build system has been re-worked and made more modular
- Installation of the manual page and other documentation can now be skipped or performed separately
- The compiled manual page is now distributed with the source. This removes
pandoc
as a build dependency.
💡 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
If you wish to contribute to the program's development, clone the devel branch.
$ git clone -b devel https://github.com/plp13/qman qman
Qman is written in plain C, and thus requires a compiler such as gcc
or
clang
. Its only library dependencies are glibc
, ncurses
, hinit
, and
zlib
. It uses the meson
build system.
The program 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.
The following commands should install all necessary dependencies for different operating systems and distros:
# pacman -Sy
# pacman -S base-devel git meson libinih python-cogapp man-db man-pages
# apt update
# apt install build-essential git meson pkg-config libncurses-dev libinih-dev pipx man-db
$ pipx install cogapp
💡 Note
By default,
pipx
will install thecog
executable in~/.local/bin
. You will have to add this directory to your path before proceeding withmeson setup
.
# apt update
# apt install build-essential git meson pkg-config libncurses-dev libinih-dev python3-pip man-db
# pip install cogapp
# dnf install epel-release
# dnf update
# dnf group install "Development Tools"
# dnf install man-db man-pages ncurses-devel python3-pip
# dnf --enablerepo devel install meson inih-devel
# pip install cogapp
💡 Note
These steps should also work with Red Hat Enterprise Linux 9 and AlmaLinux 9.
# dnf install epel-release
# dnf update
# dnf group install "Development Tools"
# dnf install man-db man-pages ncurses-devel python3-pip inih-devel
# dnf --enablerepo devel install meson
# pip3 install cogapp
💡 Note
These steps should also work with Red Hat Enterprise Linux 9 and AlmaLinux 9.
# apt update
# apt install build-essential git meson cmake pkg-config libncurses-dev libinih-dev python3-cogapp man-db
# apt update
# apt install build-essential git meson cmake pkg-config libncurses-dev libinih-dev python3-pip man-db
# pip install cogapp
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 compile
command withninja
.
For Arch Linux users, there is a an AUR package.
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
qman
without 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=true
to 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.