manpages

What is the best way to distribute manpages for executable scripts in PEAR? How can these manpages be integrated with the PEAR manual? I'm working with the PHP_CodeSniffer maintainer on a PHP_CodeSniffer Debian package: http://packages.debian.org/php-codesniffer PHP_CodeSniffer includes an executable script "phpcs", and I'd like to include a manpage for this script in the Debian package. There's an excellent PHP_CodeSniffer section of the PEAR manual, in DocBook format: cvs -z6 -d:pserver:cvsread@cvs.php.net:/repository co -P peardoc - and stylesheets are available in Debian for converting DocBook to manpage format: http://cgi.sfu.ca/~jdbates/tmp/php-codesniffer/200803210/manpage.xml.ex - but the PEAR manual section contains multiple <refentry> elements and the manpage stylesheet creates a manpage for each one. I could use some XSLT to convert the whole section to one <refentry>, but the content of the section, as well as the markup, differs in style from that of the above manpage.xml.ex: To make the PEAR manual section look like manpage.xml.ex, I'd need so much XSLT that it would be easier to just write the manpage itself. But it would still be nice to integrate the manpage and PEAR manual somehow. Are there existing manpages anywhere in PEAR? Are there any tools or policies for their distribution? Are they written in DocBook, like the PEAR manual, or other formats? Which is the best format to use? Are manpages integrated with the PEAR manual in any way? Could they be? At the moment, I plan on using the help2man script to generate a manpage from phpcs' --help output: http://www.gnu.org/software/help2man/ http://cgi.sfu.ca/~jdbates/tmp/php-codesniffer/200803280/phpcs.1 Thanks and best wishes, Jack