31 August 2010

Generating manpages with help2man

To quote the ftp-masters REJECT-FAQ :

  • Write manpages. Yes. Really. Write them. Well. It's basically: If your program/tool has a help and version commandline option you can simply run help2man and have a working start.


What may not be obvious to the recently REJECTed developer is actually how to use help2man. To try t0 explain the process a bit more verbosely, I took the liberty of writing a tutorial on the Debian wiki. Comments and corrections are welcome.


Of course, help2man-generated manpages are no substitute for real, hand-written manpages made of sweat, blood, and the Maintainer's tears, and it won't work for all packages. This is just a start, and is much better than no manpages at all.


There was a discussion on #debian-devel a couple of days ago when I brought up my creation of the above, and some wondered if it wouldn't be better to add hooks to man-db to allow package maintainers to enable manpage generation at runtime. I'm not sure if that idea will ever make it into a proposal, but, if the details of the implementation were worked out, would be much better than the above, manually generated method.

7 comments:

  1. I'm not entirely certain it's a good idea, but as man-db upstream I'm open to a patch and we can try it out. Perhaps it could be configurable somehow.

    ReplyDelete
  2. Or maybe it would be better in dh_installman or something.

    ReplyDelete
  3. The issue with doing dh_installman is that it still requires the binary be run during build. This won't work, for example, if you're cross-compiling for another arch.

    Of course, we won't run help2man on any binary by default, but only if a maintainer opts in somehow.

    ReplyDelete
  4. Matthew W. S. Bell31 August 2010 at 20:49

    Perhaps you should look at the help2man man page?

    ReplyDelete
  5. Which version of help2man is being documented on the wiki?
    On Debian Lenny, the --version-string option doesn't exist and the
    --version-option option doesn't work as a string literal:

    $help2man myprog.py
    help2man: can't get `--version' info from myprog.py

    $help2man --version-string=\program 1\ myprog.py
    Unknown option: version-string
    ...

    $help2man --version-option=\program 1\ myprog.py
    help2man: can't get `program 1' info from myprog.py

    $apt-get source help2man ; cd help2man-1.36.4/
    $grep 'version-string' * */*
    $

    ReplyDelete
  6. Ah, --version-string was added in version 1.37, so the wiki is correct for
    squeeze and sid (which have version 1.38.2)

    ReplyDelete
  7. Just the other day, I found myself having the need to write a manpage. Since I had never written one before (and didn't even really understand how manpages worked), I took the time to learn the process. After writing the manpage, I was asked by someone else to write an article about the process, so I did: http://www.2buntu.com/2011/11/02/how-to-write-a-manpage/

    ReplyDelete