[Pkg-chromium-maint] Bug#585825: gyp: lacks overview documentatio

[Jonathan Nieder]

Hi,

Timo Juhani Lindfors wrote:

> seems I did some duplication of work since I didn't check the BTS
> before writing a patch to do a very similar fix...

Sorry I missed this.

> The attached patch generates manual page using help2man but adds
> static description, authors and see also sections. Do you feel that we
> could merge these two patches so that documentation for command line
> options would be generated automatically but description, environment,
> files and see also sections would be static?

I tend to despise help2man, at least with most programs' --help output.
Off the top of my head, here are some other possibilities:

 - Combine help2man with po4a to "translate" from --help-ese to
   manpage-ese.  This way one gets a nice reminder when the --help
   output has changed.

 - Similar, but just use a sha1sum of --help output to decide whether
   the man page is stale and if so, refuse to proceed.

 - See if upstream wants a manpage/HTML manual.  If they do, submit it
   so it can be maintained as part of the upstream package.

 - gyp --manual-nroff code path parallel to gyp --help.

 - Let the manpage go out of date, but include a reference to
   --help in the DESCRIPTION section and submit at bugs.debian.org in
   the AUTHORS section as a hint to others that might help fix it.

What do you think?
Jonathan