man: use meaningful titles for <ulink>s
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 commit is contained in:
@@ -80,7 +80,7 @@
|
||||
<literal>t</literal>, <literal>d</literal> (but not
|
||||
<literal>b</literal>), as defined by the <ulink
|
||||
url="https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types">Basic
|
||||
Types</ulink> section of the D-Bus specification, and listed in
|
||||
D-Bus Types</ulink> section of the D-Bus specification, and listed in
|
||||
<citerefentry><refentrytitle>sd_bus_message_append_basic</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
|
||||
Pointer <parameter>p</parameter> must point to an array of size
|
||||
<parameter>size</parameter> bytes containing items of the
|
||||
|
||||
Reference in New Issue
Block a user