shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-21 22:04:01 +03:00
Code

man: use meaningful titles for <ulink>s

Browse Source 
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 12:43:40 +01:00
parent 69c37b26a4
commit c8cd6d7bab
12 changed files with 72 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
man/crypttab.xml
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>

22
man/resolvectl.xml
View File

@ -77,17 +77,17 @@
[[<replaceable>NAME</replaceable>] <replaceable>TYPE</replaceable>]
<replaceable>DOMAIN</replaceable></term>
<listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">DNS-SD</ulink> and <ulink
url="https://tools.ietf.org/html/rfc2782">SRV</ulink> services, depending on the specified list of
parameters. If three parameters are passed the first is assumed to be the DNS-SD service name, the
second the <constant class='dns'>SRV</constant> service type, and the third the domain to search in.
In this case a full DNS-SD style <constant class='dns'>SRV</constant> and <constant
class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the first is
assumed to be the <constant class='dns'>SRV</constant> service type, and the second the domain to look
in. In this case no <constant class='dns'>TXT</constant> resource record is requested. Finally, if
only one parameter is specified, it is assumed to be a domain name, that is already prefixed with an
<constant class='dns'>SRV</constant> type, and an <constant class='dns'>SRV</constant> lookup is done
(no <constant class='dns'>TXT</constant>).</para>
<listitem><para>Resolve <ulink url="https://tools.ietf.org/html/rfc6763">RFC 6763 DNS-SD</ulink> and
<ulink url="https://tools.ietf.org/html/rfc2782">RFC 2782 SRV</ulink> services, depending on the
specified list of parameters. If three parameters are passed the first is assumed to be the DNS-SD
service name, the second the <constant class='dns'>SRV</constant> service type, and the third the
domain to search in. In this case a full DNS-SD style <constant class='dns'>SRV</constant> and
<constant class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the
first is assumed to be the <constant class='dns'>SRV</constant> service type, and the second the
domain to look in. In this case no <constant class='dns'>TXT</constant> resource record is requested.
Finally, if only one parameter is specified, it is assumed to be a domain name, that is already
prefixed with an <constant class='dns'>SRV</constant> type, and an <constant
class='dns'>SRV</constant> lookup is done (no <constant class='dns'>TXT</constant>).</para>
<xi:include href="version-info.xml" xpointer="v239"/></listitem>
</varlistentry>

2
man/sd-id128.xml
View File

@ -190,7 +190,7 @@ int main(int argc, char **argv) {
are similar to
<constant>SD_ID128_FORMAT_STR</constant> and <function>SD_ID128_MAKE_STR()</function>,
but include separating hyphens to conform to the
"<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">canonical representation</ulink>".
"<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">UUID canonical representation</ulink>".
They format the string based on <ulink
url="https://tools.ietf.org/html/rfc4122">RFC4122</ulink> Variant 1 rules, i.e. converting from Big
Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably

2
man/sd_bus_error.xml
View File

@ -163,7 +163,7 @@
<listitem><para>The <structfield>name</structfield> field contains a short identifier of an error. It
should follow the rules for error names described in the D-Bus specification, subsection <ulink
url="https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names">Valid
Names</ulink>. A number of common, standardized error names are described in
D-Bus Names</ulink>. A number of common, standardized error names are described in
<citerefentry><refentrytitle>sd-bus-errors</refentrytitle><manvolnum>3</manvolnum></citerefentry>, but
additional domain-specific errors may be defined by applications.</para></listitem>

2
man/sd_bus_message_append_array.xml
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

2
man/sd_bus_set_description.xml
View File

@ -121,7 +121,7 @@
i.e. lack of authentication, of the bus peer. This function must be called before the bus is
started. See the
<ulink url="view-source:https://dbus.freedesktop.org/doc/dbus-specification.html#auth-mechanisms">
Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
D-Bus Authentication Mechanisms</ulink> section of the D-Bus specification for details.</para>
<para><function>sd_bus_is_anonymous()</function> returns true if the bus connection allows
anonymous authentication (in the sense described in previous paragraph).</para>

4
man/systemd-id128.xml
View File

@ -137,8 +137,8 @@
<term><option>--uuid</option></term>
<listitem><para>Generate output as a UUID formatted in the "canonical representation", with five
groups of digits separated by hyphens. See the
<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">wikipedia</ulink>
groups of digits separated by hyphens. See the Wikipedia entry for
<ulink url="https://en.wikipedia.org/wiki/Universally_unique_identifier#Format">Universally Unique Identifiers</ulink>
for more discussion.</para>
<xi:include href="version-info.xml" xpointer="v244"/></listitem>

10
man/systemd-sleep.conf.xml
View File

@ -153,9 +153,9 @@
be aborted.</para>
<para>The allowed set of values is determined by the kernel and is shown in the file itself (use
<command>cat /sys/power/disk</command> to display). See <ulink
url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
kernel documentation</ulink> for more details.</para>
<command>cat /sys/power/disk</command> to display). See the kernel documentation page
<ulink url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
<para>
<citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
@ -175,8 +175,8 @@
<para>The allowed set of values is determined by the kernel and is shown in the file itself (use
<command>cat /sys/power/state</command> to display). See <ulink
url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">the
kernel documentation</ulink> for more details.</para>
url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
<para>
<citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>

4
man/systemd-system.conf.xml
View File

@ -461,8 +461,8 @@
case of the system manager, this includes variables set by the kernel based on the kernel command line.</para>
<para>Setting environment variables for the manager process may be useful to modify its behaviour.
See <ulink url="https://systemd.io/ENVIRONMENT">ENVIRONMENT</ulink> for a descriptions of some
variables understood by <command>systemd</command>.</para>
See <ulink url="https://systemd.io/ENVIRONMENT">Known Environment Variables</ulink> for a
descriptions of some variables understood by <command>systemd</command>.</para>
<para>Simple <literal>%</literal>-specifier expansion is supported, see below for a list of supported
specifiers.</para>

66
man/systemd.exec.xml
View File

@ -166,8 +166,9 @@
or loopback file instead of a directory. The device node or file system image file needs to contain a
file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table
with only a single Linux-compatible partition, or a set of file systems within a GPT partition table
that follows the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
Specification</ulink>.</para>
that follows the
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
Discoverable Partitions Specification</ulink>.</para>
<para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
<literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is
@ -207,8 +208,9 @@
<citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>Valid partition names follow the <ulink
url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>:
<para>Valid partition names follow the
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
Discoverable Partitions Specification</ulink>:
<constant>root</constant>, <constant>usr</constant>, <constant>home</constant>, <constant>srv</constant>,
<constant>esp</constant>, <constant>xbootldr</constant>, <constant>tmp</constant>,
<constant>var</constant>.</para>
@ -302,8 +304,9 @@
<para>This option is supported only for disk images that contain a single file system, without an
enveloping partition table. Images that contain a GPT partition table should instead include both
root file system and matching Verity data in the same image, implementing the <ulink
url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.</para>
root file system and matching Verity data in the same image, implementing the
<ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
Discoverable Partitions Specification</ulink>.</para>
<xi:include href="system-only.xml" xpointer="singular"/>
@ -831,9 +834,10 @@ CapabilityBoundingSet=~CAP_B CAP_C</programlisting>
<varname>SystemCallFilter=</varname>, or <varname>SystemCallLog=</varname> are specified. Note that
even if this setting is overridden by them, <command>systemctl show</command> shows the original
value of this setting. In case the service will be run in a new mount namespace anyway and SELinux is
disabled, all file systems are mounted with <constant>MS_NOSUID</constant> flag. Also see <ulink
url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges
Flag</ulink>.</para>
disabled, all file systems are mounted with <constant>MS_NOSUID</constant> flag. Also see
the kernel document
<ulink url="https://docs.kernel.org/userspace-api/no_new_privs.html">No New Privileges Flag</ulink>.
</para>
<para>Note that this setting only has an effect on the unit's processes themselves (or any processes
directly or indirectly forked off them). It has no effect on processes potentially invoked on request
@ -2787,37 +2791,39 @@ SystemCallErrorNumber=EPERM</programlisting>
<listitem><para>Similar to <varname>Environment=</varname>, but reads the environment variables from
a text file. The text file should contain newline-separated variable assignments. Empty lines, lines
without an <literal>=</literal> separator, or lines starting with <literal>;</literal> or
<literal>#</literal> will be ignored, which may be used for commenting. The file must be UTF-8
encoded. Valid characters are <ulink
url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink> other than
<ulink url="https://www.unicode.org/glossary/#noncharacter">noncharacters</ulink>, U+0000 NUL, and
U+FEFF <ulink url="https://www.unicode.org/glossary/#byte_order_mark">byte order mark</ulink>.
Control codes other than NUL are allowed.</para>
<literal>#</literal> will be ignored, which may be used for commenting. The file must be encoded with
UTF-8. Valid characters are
<ulink url="https://www.unicode.org/glossary/#unicode_scalar_value">unicode scalar values</ulink>
other than
<ulink url="https://www.unicode.org/glossary/#noncharacter">unicode noncharacters</ulink>,
<constant>U+0000</constant> <constant>NUL</constant>, and <constant>U+FEFF</constant>
<ulink url="https://www.unicode.org/glossary/#byte_order_mark">unicode byte order mark</ulink>.
Control codes other than <constant>NUL</constant> are allowed.</para>
<para>In the file, an unquoted value after the <literal>=</literal> is parsed with the same backslash-escape
rules as <ulink
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">unquoted
text</ulink> in a POSIX shell, but unlike in a shell, interior whitespace is preserved and quotes after the
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_01">POSIX shell unquoted
text</ulink>, but unlike in a shell, interior whitespace is preserved and quotes after the
first non-whitespace character are preserved. Leading and trailing whitespace (space, tab, carriage return) is
discarded, but interior whitespace within the line is preserved verbatim. A line ending with a backslash will be
continued to the following one, with the newline itself discarded. A backslash
<literal>\</literal> followed by any character other than newline will preserve the following character, so that
<literal>\\</literal> will become the value <literal>\</literal>.</para>
<para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span multiple lines
and contain any character verbatim other than single quote, like <ulink
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">single-quoted
text</ulink> in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace
outside of the single quotes is discarded.</para>
<para>In the file, a <literal>'</literal>-quoted value after the <literal>=</literal> can span
multiple lines and contain any character verbatim other than single quote, like <ulink
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_02">POSIX
shell single-quoted text</ulink>. No backslash-escape sequences are recognized. Leading and trailing
whitespace outside of the single quotes is discarded.</para>
<para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span multiple lines,
and the same escape sequences are recognized as in <ulink
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">double-quoted
text</ulink> of a POSIX shell. Backslash (<literal>\</literal>) followed by any of <literal>"\`$</literal> will
preserve that character. A backslash followed by newline is a line continuation, and the newline itself is
discarded. A backslash followed by any other character is ignored; both the backslash and the following
character are preserved verbatim. Leading and trailing whitespace outside of the double quotes is
discarded.</para>
<para>In the file, a <literal>"</literal>-quoted value after the <literal>=</literal> can span
multiple lines, and the same escape sequences are recognized as in <ulink
url="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_02_03">POSIX
shell double-quoted text</ulink>. Backslash (<literal>\</literal>) followed by any of
<literal>"\`$</literal> will preserve that character. A backslash followed by newline is a line
continuation, and the newline itself is discarded. A backslash followed by any other character is
ignored; both the backslash and the following character are preserved verbatim. Leading and trailing
whitespace outside of the double quotes is discarded.</para>
<para>The argument passed should be an absolute filename or wildcard expression, optionally prefixed with
<literal>-</literal>, which indicates that if the file does not exist, it will not be read and no error or

8
man/systemd.netdev.xml
View File

@ -712,11 +712,11 @@
<varlistentry>
<term><varname>ReduceARPProxy=</varname></term>
<listitem>
<para>Takes a boolean. When true, bridge-connected VXLAN tunnel
endpoint answers ARP requests from the local bridge on behalf
of remote Distributed Overlay Virtual Ethernet
<para>Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from
the local bridge on behalf of remote
<ulink url="https://en.wikipedia.org/wiki/Distributed_Overlay_Virtual_Ethernet">
(DOVE)</ulink> clients. Defaults to false.</para>
Distributed Overlay Virtual Ethernet (DOVE)</ulink>
clients. Defaults to false.</para>
<xi:include href="version-info.xml" xpointer="v233"/>
</listitem>

3
man/udev.xml
View File

@ -136,7 +136,8 @@
backslash, lowercase t, backslash, lowercase n.</para>
<para>The string can be prefixed with a lowercase e (e"string\n") to mark the string as
<ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">C-style escaped</ulink>.
C-style escaped, see
<ulink url="https://en.wikipedia.org/wiki/Escape_sequences_in_C#Table_of_escape_sequences">Escape sequences in C</ulink>.
For example, e"string\n" is parsed as 7 characters: 6 lowercase letters and a newline.
This can be useful for writing special characters when a kernel driver requires them.</para>