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:
Zbigniew Jędrzejewski-Szmek
2023-11-06 20:16:34 +01:00
parent 69c37b26a4
commit c8cd6d7bab
12 changed files with 72 additions and 63 deletions
+1 -1
View File
@@ -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