[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: RFS: Authomated theorem prover E (AKA eprover)

On Sun, 22 Feb 2009 09:31:59 -0500
Ruben Molina <rmolina@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).



Neil Williams

Attachment: pgpPw1gnkJLXq.pgp
Description: PGP signature

Reply to: