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
