- 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.
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.
ReplyDeleteOr maybe it would be better in dh_installman or something.
ReplyDeleteThe 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.
ReplyDeleteOf course, we won't run help2man on any binary by default, but only if a maintainer opts in somehow.
Perhaps you should look at the help2man man page?
ReplyDeleteWhich version of help2man is being documented on the wiki?
ReplyDeleteOn 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' * */*
$
Ah, --version-string was added in version 1.37, so the wiki is correct for
ReplyDeletesqueeze and sid (which have version 1.38.2)
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