[[https://melpa.org/#/noman][file:https://melpa.org/packages/noman-badge.svg]]
I primarily wrote this package to navigate the command line help from ~kubectl~ and ~aws~, both of which have nested sub-commands, and quite verbose (and helpful!) command line help.
Neither of these programs ships with ~man~ pages, or similar offline documentation. I find myself consulting the command line help often, but struggling to find the experience very ergonomic.
This package aims to make the experience of browsing command line help more pleasant.
[[./screencast.gif]]
** Installation Noman is on MELPA so you can install it directly with:
M-x package-refresh-contents RET M-x package-install RET noman RET
If you use ~use-package~, you could also install Noman with:
(use-package noman :ensure t)
** Usage The entrypoint for this package is the ~noman~ command:
M-x noman RET
When prompted for a command, enter a program in your ~PATH~, e.g. ~kubectl~.
Noman then tries to run the command with the ~--help~ or ~help~ suffixes, and parse the output. Parsing the output simply involves looking for subcommands, and turning them into links for subsequent invocations of ~noman~.
The default key-bindings are as follows:
| Key | Description |
|-------------+-------------------------------------|
| ~n~ | Next line |
| ~p~ | Previous line |
| ~q~ | Quit the window |
| ~g~ or ~m~ | Select a subcommand to display |
| ~G~ | Run ~noman~ for a different command |
| ~l~ | Back to the previous subcommand |
| ~TAB~ | Forward button |
| ~
** Shell built-ins Noman also supports displaying help for shell built-in commands using a prefix argument:
C-u M-x noman RET
By default, Noman will use your system shell for this. If you want to use a different shell, you can customise the ~noman-shell-file-name~ variable:
(setq noman-shell-file-name "/bin/bash")
** Customisation *** Custom parsing functions Custom parsing functions can be added to ~noman-parsing-functions~ to add support for programs whose help does not work with Noman out-of-the-box. For an example of how this works, you can read how the AWS CLI is supported:
(add-to-list 'noman-parsing-functions '("aws" . noman--make-aws-button))
** Re-using buffers By default, Noman will open all help pages in the same buffer called ~noman*~. If you would prefer different buffers for each help page, you can set the ~noman-reuse-buffers~ variable:
(setq noman-reuse-buffers nil)
** Known to work with
Tests are written using ~ert~, and can either be run directing using ~M-x ert RET~, or from a shell with ~make test~.