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. The process is straightforward, with a few caveats which I will describe below.
help2man works by passing --help or --version to your program, and parsing the output according to a lexer.
The most basic invocation is as follows:
help2man ''/path/to/your/binary''
Often, however, this simple invocation will simply not work , for example, if your application does not output --help or --version to standard output. In this case, your next try should be to check whether your application actually provides those options. If it lacks a help, you re out of luck, you might as well write a man page by hand. If it supplies a help but not a --version, don t fret, the version string is trivially easy to write. Pass --version-string="your-program your-program's-version" to help2man to fix that.
If it supplies both of these, but for some reason they aren't picked up, pass help2man the --no-discard-stderr option, which will attempt to catch your program s output even if it doesn't put it in the expected location. (stdout).
When your man page is generated, you might find something at the end that seems a bit out of place:
SEE ALSO
The full documentation for your-application is maintained as a Texinfo manual. If the info and your-application ; programs are properly installed at your site, the command
info your-application
Wait, my program doesn't use Texinfo! you say. Well, since help2man is a GNU project, and Texinfo is the preferred way of storing GNU documentation, help2man defaults to assuming that you also live and breath Texinfo. To suppress this default, pass --no-info to help2man.
Now, we have a somewhat professional-looking manual page. The main two things it s missing is a descriptive NAME section, which, if left as-is, will generate a Lintian warning. Specify a one-liner description of the program to help2man with --name.
If your application belongs in a different man section other than the default (1), specify it using --section=.
For completeness, your man page should include an AUTHORS section, and preferably a SEE ALSO with pointers to the rest of the manual, if applicable. For this, we'll create a help2man include file. Here s one such file I created for Rainbow:
[authors] .B Rainbow was primarily written by Michael Stone and Noah Kantrowitz. [see also] Full documentation for the .B rainbow suite is stored at http://wiki.laptop.org/go/Rainbow
You can include that template (which I usually put in debian/help2man.include) via the --include= option.
Now, to include the result of your work in the Debian package you re building, you have to take into account that help2man works by actually running your package. This means, for example, that you shouldn't have it run during the build process, because buildds are slow and overworked, and if, for example, your program is being cross-compiled, executing your program will fail.
Add a custom build target that generates your man page, and puts it in debian/. Run the target, and check the output. You should re-run this target whenever your package s options change. Finally, include the path to that man page in your debian/ package-name.manpages.
Now you're done! Keep in mind that this is not a substitute for writing proper man pages, but this is better than having none at all. For that, I highly recommend using pandoc's -s -w man options.