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
+6 -4
View File
@@ -556,8 +556,9 @@
<para>Note that VeraCrypt enforces a minimal allowed PIM value depending on the
password strength and the hash algorithm used for key derivation, however
<option>veracrypt-pim=</option> is not checked against these bounds.
<ulink url="https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html">See
documentation</ulink> for more information.</para>
See
<ulink url="https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20%28PIM%29.html">Veracrypt Personal Iterations Multiplier</ulink>
documentation for more information.</para>
<xi:include href="version-info.xml" xpointer="v254"/>
</listitem>
@@ -980,8 +981,9 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac
<itemizedlist>
<listitem><para>We use RSA2048, which is the longest key size current Yubikeys support</para></listitem>
<listitem><para>We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes,
<ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">see
documentation</ulink>.</para></listitem>
see
<ulink url="https://developers.yubico.com/PIV/Introduction/Certificate_slots.html">Yubico PIV certificate slots</ulink>.
</para></listitem>
</itemizedlist>
</example>