As pointed out in https://github.com/systemd/systemd/issues/29814, we need to
use phrases are are meaningful on their own, because the man page formatter
creates a list at the bottom. With <ulink>see docs</ulink>, we end up with:
NOTES:
1. see docs
https://some.url/page
2. see docs
https://some.url/page2
which is not very useful :(
Also, the text inside the tag should not include punctuation.
Python helper:
from xml_helper import xml_parse
for p in glob.glob('../man/*.xml'):
t = xml_parse(p)
ulinks = t.iterfind('.//ulink')
for ulink in ulinks:
if ulink.text is None: continue
text = ' '.join(ulink.text.split())
print(f'{p}: {text}')
This tries to add information about when each option was added. It goes
back to version 183.
The version info is included from a separate file to allow generating it,
which would allow more control on the formatting of the final output.
sd-bus objects use hashmaps, which use module-global state, so it is not safe
to pass a sd-bus object created by a module instance to another module instance
(e.g.: when two libraries static linking sd-bus are pulled in a single process).
Initialize a random per-module origin id and store it in the object, and compare
it when entering a public API, and error out if they don't match, together with
the PID.
Since f4b2933ee7
if a description is not set, sd_bus_open_with_description returns -ENXIO, but the
documnetation stated that it returned successfully with a NULL string.
Logically, this is better, because we're describing a subset of possible
return values. Visually this also looks quite good because groff renders
refsect2 much less prominently.
Also rewrap things, add <constant> in various places, fix some typos.
The "include" files had type "book" for some raeason. I don't think this
is meaningful. Let's just use the same everywhere.
$ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
No need to waste space, and uniformity is good.
$ perl -i -0pe 's|\n+<!--\s*SPDX-License-Identifier: LGPL-2.1..\s*-->|\n<!-- SPDX-License-Identifier: LGPL-2.1+ -->|gms' man/*.xml
