From c8cd6d7bab8264fa0ebf08a5b170758ce13dac92 Mon Sep 17 00:00:00 2001 From: Zbigniew Jędrzejewski-Szmek Date: Mon, 6 Nov 2023 12:43:40 +0100 Subject: man: use meaningful titles for 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 see docs, 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}') --- man/crypttab.xml | 10 +++--- man/resolvectl.xml | 22 ++++++------ man/sd-id128.xml | 2 +- man/sd_bus_error.xml | 2 +- man/sd_bus_message_append_array.xml | 2 +- man/sd_bus_set_description.xml | 2 +- man/systemd-id128.xml | 4 +-- man/systemd-sleep.conf.xml | 10 +++--- man/systemd-system.conf.xml | 4 +-- man/systemd.exec.xml | 68 ++++++++++++++++++++----------------- man/systemd.netdev.xml | 8 ++--- man/udev.xml | 3 +- 12 files changed, 73 insertions(+), 64 deletions(-) (limited to 'man') diff --git a/man/crypttab.xml b/man/crypttab.xml index fa60599301..e94bf1ca17 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -556,8 +556,9 @@ Note that VeraCrypt enforces a minimal allowed PIM value depending on the password strength and the hash algorithm used for key derivation, however is not checked against these bounds. - See - documentation for more information. + See + Veracrypt Personal Iterations Multiplier + documentation for more information. @@ -980,8 +981,9 @@ external /dev/sda3 keyfile:LABEL=keydev keyfile-timeout=10s,cipher=xchac We use RSA2048, which is the longest key size current Yubikeys support We use Yubikey key slot 9d, since that's apparently the keyslot to use for decryption purposes, - see - documentation. + see + Yubico PIV certificate slots. + diff --git a/man/resolvectl.xml b/man/resolvectl.xml index 549dbbd2b7..4498732656 100644 --- a/man/resolvectl.xml +++ b/man/resolvectl.xml @@ -77,17 +77,17 @@ [[NAME] TYPE] DOMAIN - Resolve DNS-SD and SRV 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 SRV service type, and the third the domain to search in. - In this case a full DNS-SD style SRV and TXT lookup is executed. If only two parameters are specified, the first is - assumed to be the SRV service type, and the second the domain to look - in. In this case no TXT 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 - SRV type, and an SRV lookup is done - (no TXT). + Resolve RFC 6763 DNS-SD and + RFC 2782 SRV 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 SRV service type, and the third the + domain to search in. In this case a full DNS-SD style SRV and + TXT lookup is executed. If only two parameters are specified, the + first is assumed to be the SRV service type, and the second the + domain to look in. In this case no TXT 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 SRV type, and an SRV lookup is done (no TXT). diff --git a/man/sd-id128.xml b/man/sd-id128.xml index 4021b8844b..d264220b0b 100644 --- a/man/sd-id128.xml +++ b/man/sd-id128.xml @@ -190,7 +190,7 @@ int main(int argc, char **argv) { are similar to SD_ID128_FORMAT_STR and SD_ID128_MAKE_STR(), but include separating hyphens to conform to the - "canonical representation". + "UUID canonical representation". They format the string based on RFC4122 Variant 1 rules, i.e. converting from Big Endian byte order. This matches behaviour of most other Linux userspace infrastructure. It's probably diff --git a/man/sd_bus_error.xml b/man/sd_bus_error.xml index 847051a6a2..3f7a28ccaf 100644 --- a/man/sd_bus_error.xml +++ b/man/sd_bus_error.xml @@ -163,7 +163,7 @@ The name field contains a short identifier of an error. It should follow the rules for error names described in the D-Bus specification, subsection Valid - Names. A number of common, standardized error names are described in + D-Bus Names. A number of common, standardized error names are described in sd-bus-errors3, but additional domain-specific errors may be defined by applications. diff --git a/man/sd_bus_message_append_array.xml b/man/sd_bus_message_append_array.xml index da72b78cb0..ea8f532ab6 100644 --- a/man/sd_bus_message_append_array.xml +++ b/man/sd_bus_message_append_array.xml @@ -80,7 +80,7 @@ t, d (but not b), as defined by the Basic - Types section of the D-Bus specification, and listed in + D-Bus Types section of the D-Bus specification, and listed in sd_bus_message_append_basic3. Pointer p must point to an array of size size bytes containing items of the diff --git a/man/sd_bus_set_description.xml b/man/sd_bus_set_description.xml index 0cc0ee77e9..0b49ba3a3b 100644 --- a/man/sd_bus_set_description.xml +++ b/man/sd_bus_set_description.xml @@ -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 - Authentication Mechanisms section of the D-Bus specification for details. + D-Bus Authentication Mechanisms section of the D-Bus specification for details. sd_bus_is_anonymous() returns true if the bus connection allows anonymous authentication (in the sense described in previous paragraph). diff --git a/man/systemd-id128.xml b/man/systemd-id128.xml index 32c5af9671..d9378b69df 100644 --- a/man/systemd-id128.xml +++ b/man/systemd-id128.xml @@ -137,8 +137,8 @@ Generate output as a UUID formatted in the "canonical representation", with five - groups of digits separated by hyphens. See the - wikipedia + groups of digits separated by hyphens. See the Wikipedia entry for + Universally Unique Identifiers for more discussion. diff --git a/man/systemd-sleep.conf.xml b/man/systemd-sleep.conf.xml index 4a04263c1a..ee13ce8703 100644 --- a/man/systemd-sleep.conf.xml +++ b/man/systemd-sleep.conf.xml @@ -153,9 +153,9 @@ be aborted. The allowed set of values is determined by the kernel and is shown in the file itself (use - cat /sys/power/disk to display). See the - kernel documentation for more details. + cat /sys/power/disk to display). See the kernel documentation page + + Basic sysfs Interfaces for System Suspend and Hibernation for more details. systemd-suspend-then-hibernate.service8 @@ -175,8 +175,8 @@ The allowed set of values is determined by the kernel and is shown in the file itself (use cat /sys/power/state to display). See the - kernel documentation for more details. + 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 for more details. systemd-suspend-then-hibernate.service8 diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index ac2be5a5c2..3c06b65f93 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -461,8 +461,8 @@ case of the system manager, this includes variables set by the kernel based on the kernel command line. Setting environment variables for the manager process may be useful to modify its behaviour. - See ENVIRONMENT for a descriptions of some - variables understood by systemd. + See Known Environment Variables for a + descriptions of some variables understood by systemd. Simple %-specifier expansion is supported, see below for a list of supported specifiers. diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index e9cef24d18..f5d68f6c47 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -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 Discoverable Partitions - Specification. + that follows the + + Discoverable Partitions Specification. When DevicePolicy= is set to closed or strict, or set to auto and DeviceAllow= is @@ -207,8 +208,9 @@ mount8. - Valid partition names follow the Discoverable Partitions Specification: + Valid partition names follow the + + Discoverable Partitions Specification: root, usr, home, srv, esp, xbootldr, tmp, var. @@ -302,8 +304,9 @@ 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 Discoverable Partitions Specification. + root file system and matching Verity data in the same image, implementing the + + Discoverable Partitions Specification. @@ -831,9 +834,10 @@ CapabilityBoundingSet=~CAP_B CAP_C SystemCallFilter=, or SystemCallLog= are specified. Note that even if this setting is overridden by them, systemctl show 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 MS_NOSUID flag. Also see No New Privileges - Flag. + disabled, all file systems are mounted with MS_NOSUID flag. Also see + the kernel document + No New Privileges Flag. + 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 Similar to Environment=, but reads the environment variables from a text file. The text file should contain newline-separated variable assignments. Empty lines, lines without an = separator, or lines starting with ; or - # will be ignored, which may be used for commenting. The file must be UTF-8 - encoded. Valid characters are unicode scalar values other than - noncharacters, U+0000 NUL, and - U+FEFF byte order mark. - Control codes other than NUL are allowed. + # will be ignored, which may be used for commenting. The file must be encoded with + UTF-8. Valid characters are + unicode scalar values + other than + unicode noncharacters, + U+0000 NUL, and U+FEFF + unicode byte order mark. + Control codes other than NUL are allowed. In the file, an unquoted value after the = is parsed with the same backslash-escape rules as unquoted - text 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, 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 \ followed by any character other than newline will preserve the following character, so that \\ will become the value \. - In the file, a '-quoted value after the = can span multiple lines - and contain any character verbatim other than single quote, like single-quoted - text in a POSIX shell. No backslash-escape sequences are recognized. Leading and trailing whitespace - outside of the single quotes is discarded. - - In the file, a "-quoted value after the = can span multiple lines, - and the same escape sequences are recognized as in double-quoted - text of a POSIX shell. Backslash (\) followed by any of "\`$ 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. + In the file, a '-quoted value after the = can span + multiple lines and contain any character verbatim other than single quote, like POSIX + shell single-quoted text. No backslash-escape sequences are recognized. Leading and trailing + whitespace outside of the single quotes is discarded. + + In the file, a "-quoted value after the = can span + multiple lines, and the same escape sequences are recognized as in POSIX + shell double-quoted text. Backslash (\) followed by any of + "\`$ 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. The argument passed should be an absolute filename or wildcard expression, optionally prefixed with -, which indicates that if the file does not exist, it will not be read and no error or diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 2d3e575a8b..9cad358f1e 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -712,11 +712,11 @@ ReduceARPProxy= - 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 + Takes a boolean. When true, bridge-connected VXLAN tunnel endpoint answers ARP requests from + the local bridge on behalf of remote - (DOVE) clients. Defaults to false. + Distributed Overlay Virtual Ethernet (DOVE) + clients. Defaults to false. diff --git a/man/udev.xml b/man/udev.xml index 0f524697c0..709cecfd6a 100644 --- a/man/udev.xml +++ b/man/udev.xml @@ -136,7 +136,8 @@ backslash, lowercase t, backslash, lowercase n. The string can be prefixed with a lowercase e (e"string\n") to mark the string as - C-style escaped. + C-style escaped, see + Escape sequences in C. 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. -- cgit v1.2.3