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

[Timo Juhani Lindfors]

Jonathan Nieder <jrnieder at gmail.com> writes:
> 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.

I have no experience on po4a.

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

That sounds like a good idea if you expect the --help output to change
rarely and you have the extra time to manually update man page.

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

That'd be the best option to try first imho. Is upstream bug report
the way to ask them?

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

Somehow I feel that upstream might not like this?

>  - 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.

I'm not a huge fan of this option. Since this package is intended for
developers I'd rather have somewhat odd looking manual pages that are
up to date than well written manual pages that talk about a feature
that has been silently changed behind the scenes.