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

[Bjarni Ingi Gislason]

On Thu, Dec 12, 2024 at 10:21:27AM +0000, Simon McVittie wrote:
> 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.

  I do not do merge requests; too complicated for me; needs an account,
which I do not want.

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

  It is the difference between the formatted outputs that counts (see
attachment "general.bugs").

  And differences in comment lines (\"...) in a patch.

> [...]