moreman: Man Pages for Commands without Man Pages
=========
This program generates man pages for command line tools which do not come with
proper separate man pages. For these tools `man` cannot display manual
information, `moreman` however uses the command's help string (usually
displayed via the command line option `--help`) and assembles from this a "man
page".
## Overview
`moreman` is designed as a drop-in replacement for [`man`][man]. Apart from
very few options `moreman` passes all arguments through to the man command it
eventually calls. If `moreman` is called with a tool name for which a normal
man page exists, it just passes the name through to `man`; if no normal man
page exists, `moreman` assembles the man page in the described manner and then
calls `man` for final formatting.
My personal use is inside [Emacs][emacs]: Emacs has the great feature of [Man
Page Lookup][emacs-man]: It displays each man page in its own buffer/frame, so
that you easily can view the documentation to a command while using the command
in a shell buffer in another window or frame. - And with `moreman` this extends
to all commands which provide some meaningful documentation via their help
message even if they do not have a real man page.
### A Word of Warning
`moreman` works by calling the command it wants to create the man page for with
the help option - normally `--help`. This *can* be dangerous if the command
does not expect `--help` to display the help message.
## Installation
### Requirements
At least Python 3.5 (legacy Python 2.7 might work as well) plus the [`argh`][argh]
package.
[argh]: https://github.com/neithere/argh
### Install
The tool is pip-installable: `pip install moreman` For the intended command
line use though I recommend installation via [pipx]:
pipx install moreman
## Usage
Test whether everything is set up correctly by invoking `moreman`'s help
message:
$ moreman --help
This should give you something like
```
usage: moreman [-h] [-v] [--man-cmd MAN_CMD] [-g HELP_ARG] [-f]
name [name ...]
positional arguments:
name name of the command or man page
optional arguments:
-h, --help show this help message and exit
-v, --verbose verbose output ('-v' shadows man's -v for version!)
(default: False)
--man-cmd MAN_CMD man command to be used (default: 'man')
-g HELP_ARG, --help-arg HELP_ARG
help argument to the command used to generate help
document (default: '--help')
-f, --force force to generate man page from --help even if man
page exists ('-f' shadows man's -f for whatis lookup!)
(default: False)
All other options are passed through to the 'man' command.
```
Now try to list the same info as a "man page":
$ moreman moreman
Voila! This should look like a proper man page - many man page viewers are able
to recognise this format.[^1]
[^1]: Under the hood `moreman` creates a nroff file which it passes to `man`.
### Hooking up to Emacs
In order use `moreman` in Emacs, customise the Emacs variable `manual-program`
(which is in the **man** customisation group). After checking that you can
access `moreman` from your shell prompt set `manual-program` to `moreman`and
everything should work fine.
### Help for sub commands
Some tools provide extensive help and they split it over the help messages of
multiple sub commands. moreman can utilise these sub command help messages via
the `--help-arg` option.
***Update September 2019***: Some pip installations do install a man page - in
that case this example is obsolete.
For example `pip --help` lists only some general options and pip's sub
commands; detailed info about, say, the `install` sub command is displayed only
by `pip install --help`.
But issue
moreman --help-arg="install --help" pip
and you get a "man page" for the `install` subcommand of `pip`.
This works in Emacs too: After `M-x man` enter at the prompt
`--help-arg="install --help" pip`.[^2]
[^2]: In Emacs, in order to enter the required spaces you might need to use the
`^Q <space>` key combination to circumvent Emacs' auto-complete feature at
the prompt.
## Miscellaneous
If you have difficulties, open an GitHub issue for your problem. If you made
enhancements, please create a pull request.
Also note, this project uses another little module I wrote: [ArghEx: Extensions
for Argh][arghex]
[man]: http://man7.org/linux/man-pages/man1/man.1.html
[emacs-man]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Man-Page.html#Man-Page
[emacs]: http://www.gnu.org/software/emacs/
[arghex]: https://github.com/halloleo/arghex
[pipx]: https://pipxproject.github.io/pipx/
<!-- LocalWords: moreman nroff installable argh arg subcommand
-->
Raw data
{
"_id": null,
"home_page": "https://github.com/halloleo/moreman",
"name": "moreman",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "system, man, help",
"author": "halloleo",
"author_email": "moreman@halloleo.hailmail.net",
"download_url": "https://files.pythonhosted.org/packages/b7/8f/0a43f800519c9c202567701a99231d41aaac6912271d74b958b7a7beaae9/moreman-0.3.3.tar.gz",
"platform": null,
"description": "moreman: Man Pages for Commands without Man Pages\n=========\n\nThis program generates man pages for command line tools which do not come with\nproper separate man pages. For these tools `man` cannot display manual\ninformation, `moreman` however uses the command's help string (usually\ndisplayed via the command line option `--help`) and assembles from this a \"man\npage\".\n\n## Overview\n\n`moreman` is designed as a drop-in replacement for [`man`][man]. Apart from\nvery few options `moreman` passes all arguments through to the man command it\neventually calls. If `moreman` is called with a tool name for which a normal\nman page exists, it just passes the name through to `man`; if no normal man\npage exists, `moreman` assembles the man page in the described manner and then\ncalls `man` for final formatting.\n\nMy personal use is inside [Emacs][emacs]: Emacs has the great feature of [Man\nPage Lookup][emacs-man]: It displays each man page in its own buffer/frame, so\nthat you easily can view the documentation to a command while using the command\nin a shell buffer in another window or frame. - And with `moreman` this extends\nto all commands which provide some meaningful documentation via their help\nmessage even if they do not have a real man page.\n\n### A Word of Warning\n\n`moreman` works by calling the command it wants to create the man page for with\nthe help option - normally `--help`. This *can* be dangerous if the command\ndoes not expect `--help` to display the help message.\n\n\n## Installation\n\n### Requirements\n\nAt least Python 3.5 (legacy Python 2.7 might work as well) plus the [`argh`][argh]\npackage.\n\n[argh]: https://github.com/neithere/argh\n\n### Install\n\nThe tool is pip-installable: `pip install moreman` For the intended command\nline use though I recommend installation via [pipx]:\n\n pipx install moreman\n\n## Usage\n\nTest whether everything is set up correctly by invoking `moreman`'s help\nmessage:\n\n $ moreman --help\n\nThis should give you something like\n\n```\nusage: moreman [-h] [-v] [--man-cmd MAN_CMD] [-g HELP_ARG] [-f]\n name [name ...]\n\npositional arguments:\n name name of the command or man page\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose verbose output ('-v' shadows man's -v for version!)\n (default: False)\n --man-cmd MAN_CMD man command to be used (default: 'man')\n -g HELP_ARG, --help-arg HELP_ARG\n help argument to the command used to generate help\n document (default: '--help')\n -f, --force force to generate man page from --help even if man\n page exists ('-f' shadows man's -f for whatis lookup!)\n (default: False)\n\nAll other options are passed through to the 'man' command.\n```\n\nNow try to list the same info as a \"man page\":\n\n $ moreman moreman\n\nVoila! This should look like a proper man page - many man page viewers are able\nto recognise this format.[^1]\n\n[^1]: Under the hood `moreman` creates a nroff file which it passes to `man`.\n\n### Hooking up to Emacs\n\nIn order use `moreman` in Emacs, customise the Emacs variable `manual-program`\n(which is in the **man** customisation group). After checking that you can\naccess `moreman` from your shell prompt set `manual-program` to `moreman`and\neverything should work fine.\n\n### Help for sub commands\n\nSome tools provide extensive help and they split it over the help messages of\nmultiple sub commands. moreman can utilise these sub command help messages via\nthe `--help-arg` option.\n\n***Update September 2019***: Some pip installations do install a man page - in\nthat case this example is obsolete.\n\nFor example `pip --help` lists only some general options and pip's sub\ncommands; detailed info about, say, the `install` sub command is displayed only\nby `pip install --help`.\n\nBut issue\n\n moreman --help-arg=\"install --help\" pip \n\nand you get a \"man page\" for the `install` subcommand of `pip`.\n\nThis works in Emacs too: After `M-x man` enter at the prompt\n`--help-arg=\"install --help\" pip`.[^2]\n\n[^2]: In Emacs, in order to enter the required spaces you might need to use the\n `^Q <space>` key combination to circumvent Emacs' auto-complete feature at\n the prompt.\n\n\n## Miscellaneous \n\nIf you have difficulties, open an GitHub issue for your problem. If you made\nenhancements, please create a pull request.\n\nAlso note, this project uses another little module I wrote: [ArghEx: Extensions\nfor Argh][arghex]\n\n[man]: http://man7.org/linux/man-pages/man1/man.1.html\n[emacs-man]: http://www.gnu.org/software/emacs/manual/html_node/emacs/Man-Page.html#Man-Page\n[emacs]: http://www.gnu.org/software/emacs/\n[arghex]: https://github.com/halloleo/arghex\n[pipx]: https://pipxproject.github.io/pipx/\n\n\n<!-- LocalWords: moreman nroff installable argh arg subcommand\n -->\n",
"bugtrack_url": null,
"license": "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
"summary": "Man Pages for Commands without Man Pages",
"version": "0.3.3",
"project_urls": {
"Homepage": "https://github.com/halloleo/moreman"
},
"split_keywords": [
"system",
" man",
" help"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b39b2d3b6bb0fc68337067707917d2c6297a6cdcb733cd4c69fa9f6a1e907490",
"md5": "ccb15fb776984ec917bdb0b336d1829f",
"sha256": "850a2aa4628b575a2e5e4e42530af968873f43af64969ebb06b77f6b0906b924"
},
"downloads": -1,
"filename": "moreman-0.3.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccb15fb776984ec917bdb0b336d1829f",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 19533,
"upload_time": "2024-06-11T03:01:54",
"upload_time_iso_8601": "2024-06-11T03:01:54.251215Z",
"url": "https://files.pythonhosted.org/packages/b3/9b/2d3b6bb0fc68337067707917d2c6297a6cdcb733cd4c69fa9f6a1e907490/moreman-0.3.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b78f0a43f800519c9c202567701a99231d41aaac6912271d74b958b7a7beaae9",
"md5": "f4c87adf95f98ef35a80ee8f4b2dc412",
"sha256": "af0bcdba8c23bc4f0d5f305c6db80e46c1bbfe16ff36e59034f31af6794ab635"
},
"downloads": -1,
"filename": "moreman-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "f4c87adf95f98ef35a80ee8f4b2dc412",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19926,
"upload_time": "2024-06-11T03:01:55",
"upload_time_iso_8601": "2024-06-11T03:01:55.962610Z",
"url": "https://files.pythonhosted.org/packages/b7/8f/0a43f800519c9c202567701a99231d41aaac6912271d74b958b7a7beaae9/moreman-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-11 03:01:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "halloleo",
"github_project": "moreman",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "moreman"
}
JSON
