Re: Should we standardize a way to create and maintain manpages?

[Andrius Merkys <merkys@debian.org>]

Hi Nilesh,

On 2020-12-20 15:10, Nilesh Patra wrote:
> As a result, I was wondering if there might be some way to automate this
> bit, or alternatively, use help2man during build time itself and nuke
> d/createmanpages and d/*.1 as a workaround. 
> And hence, maybe it is a good idea to standardize one practice across
> team to avoid such delta in manpage with versions?
> 
> Please let me know what you'd think is the best way forward.

Thanks for opportunity to discuss this. I myself enjoy fully automated
build time solutions (like help2man) the most, as this way manpages are
kept up-to-date with no cost at all. However, build time solutions have
their own disadvantages:

1. Unusable for arch:any programs, as they may be cross-built.

2. Requires Build-Depends containing binary Depends, but this is usually
cheap.

I would really recommend using help2man for arch:all binary packages,
but d/createmanpages approach seems inevitable for arch:any. Maybe there
is a way to forbid cross-builds, but I am not sure manpages are worth it.

Maybe the tooling could be improved to make it more difficult to forget
rebuilding d/*.1? For example, lintian warning/error reporting that
timestamps of d/*.1 are older than the newest upstream release? I think
such approach would be general enough.

Best,
Andrius