On Sun, 22 Feb 2009 09:31:59 -0500 Ruben Molina <rmol...@udea.edu.co> wrote:
> > thanks for valuable feedback. I worked on it a bit more and now it > > seems that everything is resolved and lintian is happy. Only man pages > > are a problem, the programs have a lot of options and I don't want > > just to manually duplicate 'eprover --help' etc. listings in a man > > page every time something changes. Sorry, but IMHO that is just par for the course. Write the manpage and make it useful. Add content, describe stuff that --help cannot. Explain what the program does and why certain options are used and why some might not be useful for certain operations. > check help2man :) and then expand on that content. help2man is a starter, it is never (IMHO) the complete answer to preparing any manpage. It does the first 50%, if that, in most cases. What you need to do is use doclifter after using help2man. Then edit the resulting XML (Docbook style) and generate a useful manpage using xsltproc. (The command is in a comment created by doclifter). Keep the XML in the debian/ directory and run the xsltproc command manually when you update the XML (there is no need to run it every time you build). As the XML develops, get it included upstream with the necessary xsltproc support - again, it isn't compulsory to run that every time, I usually use relevant Makefile and autoconf rules to only build the manpages once per release, although some packages do just build the manpages each time. > > I'll try to resolve it with the upstream author somehow. Meanwhile I > > put there a short man page that describes the programs and asks the > > user to run 'program --help'. I hope that'll be OK for the first > > version. It wouldn't be OK for me - I would not sponsor a package in that condition. Manpages are not some after thought - they require careful preparation, creative input, consideration of the viewpoint of ordinary users, examples, howtos, guide, introductions, descriptions, advice and even a short FAQ in some cases. As for not bothering with all that in the first release, few things get on my nerves as much as maintainers rushing uploads for the sake of their vanity. Every release should be prepared as if it is the last release to go into stable, just hoping things will be OK for the first version is often a sign of a hasty or even lazy maintainer. > I really think is better if you prepare a proper manpage, and forward it > to upstream... but people on mentors (CC'ing) can offer you other/better > options... > > Regards, > (and good look finding a sponsor) (your attitude to manpages just lost you this sponsor). http://people.debian.org/~codehelp/#lintian -- Neil Williams ============= http://www.data-freedom.org/ http://www.nosoftwarepatents.com/ http://www.linux.codehelp.co.uk/
pgpqVGZXu21Il.pgp
Description: PGP signature
