|
OK, I see that I have underestimated the task of creating a good man page. This is my first Debian package, so please be patient with me. The tools you recommend look very promising, and rst2man suggested by Ben Finney too. Just let me explain why it's difficult to create a good manual for eprover: Automated theorem provers like this are based on the state of the art in this (narrow) field of mathematics, and to understand and thoroughly document (and use properly) all its features one has to be really an expert. While this might be a good reason to have a really well written documentation, it is also a reason why it's really hard to find people who are able to write it. Unfortunately, I'm not such a person. If you look let's say at the man page of prover9 you'll see that it's just as simple (maybe even simpler) as mine. Nevertheless, eprover contains a PDF manual written by the upstream author that documents it in much more detail and it's included in the package. Wouldn't that suffice? (And I guess it has to be PDF because it contains mathematical formulae.) Anyhow, I'll try harder to find some help with producing a better man page. Best regards Petr Neil Williams wrote: > > 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/ |