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}')
The example was supposed to show how
machine-id/new/machine-id --app-specific/show --app-specific tie together, but
the verb was ommitted.
I also extended the explanation a bit and used long option form in the first
example for more clarity. In the second, more complicated example, the
one-letter form is used for brevity.
Noticed in post-review:
b37e8184a5 (r1315678438)
I'm keeping this as a separate commit. It is the first time version
information is manually added after 6a73a4f7c4
and we might want to revert this later.
https://github.com/systemd/systemd/issues/27514 requested this functionality
among other things, but it is already implemented. The man page was also
missing 'show' in the synopsis, so add that, along with an example.
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.
The article "a" goes before consonant sounds and "an" goes before vowel
sounds. This commit changes an to a for UKI, UDP, UTF-8, URL, UUID, U-Label, UI
and USB, since they start with the sound /ˌjuː/.
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
