Re: Should we standardize a way to create and maintain manpages?
On 2020-12-23 11:28, Andreas Tille wrote:
> This would possibly offer a new way to create our manpages:
>
> Fetch
>
> .SH NAME
>
> from short description and simply add a hint how to call the help
> screen of the program in question. We "simply" need to find out
> what option will show some help and add this to the manpage. So
> we offer a hint how to get help properly.
>
> What do you think about it?
This indeed could be a way to create "placeholder" manpages, especially
for arch:any packages. However, I would still use help2man for arch:all
packages, as most of the time it generates sensible manpages.
It would be great to upstream the manpage maintenance effort, just as
already suggested by lintian [1]. However, I expect upstreams to lack
the incentive for maintaining their tool manuals in yet another format,
alongside HTML/PDF or the like. Mutual advantage could be the sufficient
incentive, for instance, offering human- and machine-readable CLI
descriptions that could be reused in, for example, enveloping command
line tools in CWL/Galaxy/GUIs for command line composing. Such
descriptions could be reused to automatically produce manpages. I am
thinking of something like OpenAPI [3], but for CLI applications. Is
someone aware of formats for such descriptions? The closest I am aware
of is the CWL CommandLineTool [3], however, I know too little about it.
By the way, I have filed a wishlist bug report on lintian to implement
hint for outdated maintainer manpages [4]. Feel free to add/discuss it
there.
[1] https://lintian.debian.org/tags/maintainer-manual-page.html
[2] https://spec.openapis.org/oas/v3.0.3.html
[3] https://www.commonwl.org/v1.2/CommandLineTool.html
[4] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=978552
Best,
Andrius
Reply to: