Bug#1104820: gapplication.1: Some remarks and a patch with editorial changes for this man page

[Simon McVittie]

Control: tags -1 - patch

On Tue, 06 May 2025 at 22:10:27 +0000, Bjarni Ingi Gislason wrote:
>     Checking for defects with a new version
>
>test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man page"

You seem to be assuming in this series of bug reports that man all man
pages are maintained by hand as roff source code. This is not the case.
The source code for gapplication(1) is docs/reference/gio/gapplication.rst
in the GLib source tree, written in reStructuredText and converted to
man page (roff) format by python3-docutils.

As a result, we are not interested in stylistic points about the roff
source code or the output of lint tools: nobody is going to be editing the
roff source code for this man page by hand anyway, so suggestions that
would make it easier to hand-edit are not a productive use of anyone's
time. The only issues that are actionable for this particular man page
are those that genuinely have a user-visible impact to a user reading
the documentation with `man 1 gapplication` or `apropos gapplication`
or similar. If there is a user-visible problem with this man page,
the two possible solutions are:

1. changing the source code (.rst file) or the options passed to the
    man-page-generating tool, in the glib2.0 source package, preferably
    upstream rather than in Debian;

2. or changing the tool itself (in the python-docutils source package)
    to produce better output from the same source code, again preferably
    upstream rather than in Debian

Applying the patch you have provided to a generated file is not a valid
medium-term solution: that patch will become inapplicable when either
the man page or the generating tool changes. So I'm removing the patch
tag from this bug report. Please do not propose patches against
generated files, they will not be applied.

All maintainers (both upstream and in Debian) have limited time and many
other issues competing for our attention, and reviewing proposed patches
takes time, so please consider whether the impact of minor or cosmetic
issues is sufficiently significant that reporting them is a good use of
limited resources. I expect that you would get a better reception if you
limited this series of bug reports by prioritizing only the issues that
have a user-visible impact, and not requesting cosmetic/trivial changes
at the same time.

Thanks,
     smcv