[Pkg-utopia-maintainers] Bug#1089746: dbus-update-activation-environment.1: Some remarks about this man page

[Simon McVittie]

On Thu, 12 Dec 2024 at 03:02:18 +0000, Bjarni Ingi Gislason wrote:
>   General remarks and further material, if a diff-file exist, are in the
> attachments.

Sorry, polishing this man page is far down my list of priorities for how
to spend my limited time, especially if it involves separating functional
changes from things that are a matter of opinion. If you would like to
propose concrete changes, please open a merge request at
<https://gitlab.freedesktop.org/dbus/dbus/-/merge_requests>
so that they can be reviewed, with one commit per logical change, starting
with the changes that have the smallest amount of diffstat for the largest
amount of benefit.

You seem to be assuming that the man page was written by hand in roff
syntax, but the source code for dbus-update-activation-environment(1) is
`doc/dbus-update-activation-environment.1.xml.in` in the dbus source code,
a Docbook XML file, from which the roff version is generated using xsltproc
and docbook-xsl. The only part of this that is under the control of the
maintainers of dbus is the XML source.

If there are improvements that can be made by editing that XML, please
propose them upstream; but it looks as though some of your criticisms
could only be addressed by changing the Docbook XSL stylesheets, in
which case please report those to the upstream maintainers of the
stylesheets (ideally with proposed changes to resolve them).

In particular, if there are aspects of the output of those stylesheets
that are valid, but not how you would have written them if you were
writing roff by hand (such as applying unnecessary-but-valid escaping),
I don't consider those to be a bug at all.

>   Separate the sentences and subordinate clauses; each begins on a new
> line.  See man-pages(7) ("Conventions for source file layout") and
> "info groff" ("Input Conventions").

"Semantic line breaks" are fine as a recommendation for new code, but
applying them to an existing file is difficult to review (it would be
easy for a malicious contributor to hide a misleading text change among
mass-reformatting) for only a limited amount of benefit. It is a good
principle to follow in text that is being newly added or edited for
some other reason, and I already bear it in mind when making changes
and reviewing new contributions.

    smcv