From f223fd6addad51e1661d3baa409eb12de5065817 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Erik=20Sj=C3=B6lund?= Date: Wed, 26 Jan 2022 19:42:49 +0100 Subject: [PATCH] docs: fix typos and improve language Fix typos and improve the language by adding a few commas and a missing word. --- docs/CGROUP_DELEGATION.md | 2 +- docs/CODING_STYLE.md | 2 +- docs/CONTAINER_INTERFACE.md | 2 +- docs/ENVIRONMENT.md | 2 +- docs/GVARIANT-SERIALIZATION.md | 2 +- docs/INITRD_INTERFACE.md | 2 +- docs/JOURNAL_FILE_FORMAT.md | 2 +- docs/JOURNAL_NATIVE_PROTOCOL.md | 2 +- docs/PASSWORD_AGENTS.md | 2 +- docs/RESOLVED-VPNS.md | 2 +- docs/UIDS-GIDS.md | 4 ++-- docs/USER_GROUP_API.md | 6 +++--- docs/USER_RECORD.md | 12 ++++++------ 13 files changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/CGROUP_DELEGATION.md b/docs/CGROUP_DELEGATION.md index aeb2be97b3f..03340e7e8f7 100644 --- a/docs/CGROUP_DELEGATION.md +++ b/docs/CGROUP_DELEGATION.md @@ -356,7 +356,7 @@ but of course that's between you and those other tenants, and systemd won't care. Replicating the cgroup hierarchies in those unsupported controllers would mean replicating the full cgroup paths in them, and hence the prefixing `.slice` components too, otherwise the hierarchies will start being orthogonal -after all, and that's not really desirable. On more thing: systemd will clean +after all, and that's not really desirable. One more thing: systemd will clean up after you in the hierarchies it manages: if your daemon goes down, its cgroups will be removed too. You basically get the guarantee that you start with a pristine cgroup sub-tree for your service or scope whenever it is diff --git a/docs/CODING_STYLE.md b/docs/CODING_STYLE.md index eba1e1444e6..cd4486973e2 100644 --- a/docs/CODING_STYLE.md +++ b/docs/CODING_STYLE.md @@ -358,7 +358,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later - For every function you add, think about whether it is a "logging" function or a "non-logging" function. "Logging" functions do (non-debug) logging on their - own, "non-logging" function never log on their own (except at debug level) + own, "non-logging" functions never log on their own (except at debug level) and expect their callers to log. All functions in "library" code, i.e. in `src/shared/` and suchlike must be "non-logging". Every time a "logging" function calls a "non-logging" function, it should log about the resulting diff --git a/docs/CONTAINER_INTERFACE.md b/docs/CONTAINER_INTERFACE.md index 6607f522003..757207ce94a 100644 --- a/docs/CONTAINER_INTERFACE.md +++ b/docs/CONTAINER_INTERFACE.md @@ -277,7 +277,7 @@ care should be taken to avoid naming conflicts. `systemd` (and in particular 1. Do not drop `CAP_MKNOD` from the container. `PrivateDevices=` is a commonly used service setting that provides a service with its own, private, minimal version of `/dev/`. To set this up systemd in the container needs this - capability. If you take away the capability than all services that set this + capability. If you take away the capability, then all services that set this flag will cease to work. Use `BPF_PROG_TYPE_CGROUP_DEVICE` BPF programs — on cgroupv2 — or the `devices` controller — on cgroupv1 — to restrict what device nodes the container can create instead of taking away the capability diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md index 71d6c55010d..e8a2ce394a1 100644 --- a/docs/ENVIRONMENT.md +++ b/docs/ENVIRONMENT.md @@ -325,7 +325,7 @@ fuzzers: * `$SYSTEMD_FUZZ_RUNS` — The number of times execution should be repeated in manual invocations. -Note that is may be also useful to set `$SYSTEMD_LOG_LEVEL`, since all logging +Note that it may be also useful to set `$SYSTEMD_LOG_LEVEL`, since all logging is suppressed by default. `systemd-importd`: diff --git a/docs/GVARIANT-SERIALIZATION.md b/docs/GVARIANT-SERIALIZATION.md index c999fdd58ab..3dca54ebe3d 100644 --- a/docs/GVARIANT-SERIALIZATION.md +++ b/docs/GVARIANT-SERIALIZATION.md @@ -7,7 +7,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later # GVariant D-Bus Message Serialization -We stay close to the original dbus1 framing as possible, but make +We stay as close to the original dbus1 framing as possible, but make certain changes to adapt for GVariant. dbus1 has the following framing: diff --git a/docs/INITRD_INTERFACE.md b/docs/INITRD_INTERFACE.md index 2d1d0ac607d..3898840c56b 100644 --- a/docs/INITRD_INTERFACE.md +++ b/docs/INITRD_INTERFACE.md @@ -12,7 +12,7 @@ The Linux initrd mechanism (short for "initial RAM disk") refers to a small file system archive that is unpacked by the kernel and contains the first userspace code that runs. It typically finds and transitions into the actual root file system to use. systemd supports both initrd and initrd-less boots. If -an initrd is used it is a good idea to pass a few bits of runtime information +an initrd is used, it is a good idea to pass a few bits of runtime information from the initrd to systemd in order to avoid duplicate work and to provide performance data to the administrator. In this page we attempt to roughly describe the interfaces that exist between the initrd and systemd. These diff --git a/docs/JOURNAL_FILE_FORMAT.md b/docs/JOURNAL_FILE_FORMAT.md index f9c9fcb314c..0036ee45d68 100644 --- a/docs/JOURNAL_FILE_FORMAT.md +++ b/docs/JOURNAL_FILE_FORMAT.md @@ -297,7 +297,7 @@ STATE_ARCHIVED. If a writer is asked to write to a file that is not in STATE_OFFLINE it should immediately rotate the file and start a new one, without changing the file. -After and before the state field is changed `fdatasync()` should be executed on +After and before the state field is changed, `fdatasync()` should be executed on the file to ensure the dirty state hits disk. diff --git a/docs/JOURNAL_NATIVE_PROTOCOL.md b/docs/JOURNAL_NATIVE_PROTOCOL.md index 855f6acf30f..d3fa9b7f73c 100644 --- a/docs/JOURNAL_NATIVE_PROTOCOL.md +++ b/docs/JOURNAL_NATIVE_PROTOCOL.md @@ -17,7 +17,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later The latter is what this document is about: if you are developing a program and want to pass structured log data to `journald`, it's the Journal's native -protocol what you want to use. The systemd project provides the +protocol that you want to use. The systemd project provides the [`sd_journal_print(3)`](https://www.freedesktop.org/software/systemd/man/sd_journal_print.html) API that implements the client side of this protocol. This document explains what this interface does behind the scenes, in case you'd like to implement a diff --git a/docs/PASSWORD_AGENTS.md b/docs/PASSWORD_AGENTS.md index 7d810fbbd9f..ed204911bc0 100644 --- a/docs/PASSWORD_AGENTS.md +++ b/docs/PASSWORD_AGENTS.md @@ -34,7 +34,7 @@ It is easy to write additional agents. The basic algorithm to follow looks like Again, it is essential that you stop showing the password box/notification/status icon if the `ask.xxx` file is removed or when `NotAfter=` elapses (if it is set `!= 0`)! -It may happen that multiple password entries are pending at the same time. Your agent needs to be able to deal with that. Depending on your environment you may either choose to show all outstanding passwords at the same time or instead only one and as soon as the user replied to that one go on to the next one. +It may happen that multiple password entries are pending at the same time. Your agent needs to be able to deal with that. Depending on your environment you may either choose to show all outstanding passwords at the same time or instead only one and as soon as the user has replied to that one go on to the next one. You may test this all with manually invoking the "`systemd-ask-password`" tool on the command line. Pass `--no-tty` to ensure the password is asked via the agent system. Note that only privileged users may use this tool (after all this is intended purely for system-level passwords). diff --git a/docs/RESOLVED-VPNS.md b/docs/RESOLVED-VPNS.md index 89a5cdfacf2..e06fbc3d2f7 100644 --- a/docs/RESOLVED-VPNS.md +++ b/docs/RESOLVED-VPNS.md @@ -66,7 +66,7 @@ a network interface may configure. differentiate them. i.e. `~foo.com` is a configured routing domain, while `foo.com` would be a configured search domain. - One routing domain is particular interesting: `~.` — the catch-all routing + One routing domain is particularly interesting: `~.` — the catch-all routing domain. (The *dot* domain `.` is how DNS denotes the "root" domain, i.e. the parent domain of all domains, but itself.) When used on an interface any DNS traffic is preferably routed to its DNS servers. (A search domain – i.e. `.` diff --git a/docs/UIDS-GIDS.md b/docs/UIDS-GIDS.md index d3b7c2fe9ed..5c05bf11cb4 100644 --- a/docs/UIDS-GIDS.md +++ b/docs/UIDS-GIDS.md @@ -176,7 +176,7 @@ Systemd has compile-time default for these boundaries. Using those defaults is recommended. It will nevertheless query `/etc/login.defs` at runtime, when compiled with `-Dcompat-mutable-uid-boundaries=true` and that file is present. Support for this is considered only a compatibility feature and should not be -used except when upgrading systems which were creating with different defaults. +used except when upgrading systems which were created with different defaults. ## Considerations for container managers @@ -255,7 +255,7 @@ the artifacts the container manager persistently leaves in the system. | 2147483648…4294967294 | HIC SVNT LEONES | | | | 4294967295 | 32bit `(uid_t) -1` | Linux | | -Note that "Unused" in the table above doesn't meant that these ranges are +Note that "Unused" in the table above doesn't mean that these ranges are really unused. It just means that these ranges have no well-established pre-defined purposes between Linux, generic low-level distributions and `systemd`. There might very well be other packages that allocate from these diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md index cefe6d3dcee..ccd9f9b3d88 100644 --- a/docs/USER_GROUP_API.md +++ b/docs/USER_GROUP_API.md @@ -241,7 +241,7 @@ about existence or non-existence of a record can be returned nor any user record at all. (The `service` field is defined in order to allow implementation of daemons that provide multiple distinct user/group services over the same `AF_UNIX` socket: in order to correctly determine which service a client wants -to talk to the client needs to provide the name in each request.) +to talk to, the client needs to provide the name in each request.) The `GetGroupRecord` method call works analogously but for groups. @@ -257,7 +257,7 @@ with `more` set, so that multiple replies can be returned (since typically there are multiple members per group and also multiple groups a user is member of). As with `GetUserRecord` and `GetGroupRecord` the `service` parameter needs to contain the name of the service being talked to, in order to -allow implementation of multiple service within the same IPC socket. In case no +allow implementation of multiple services within the same IPC socket. In case no matching membership is known `NoRecordFound` is returned. The other two errors are also generated in the same cases as for `GetUserRecord` and `GetGroupRecord`. @@ -270,7 +270,7 @@ before the complete list is acquired. Note that only the `GetMemberships` call is authoritative about memberships of users in groups. i.e. it should not be considered sufficient to check the `memberOf` field of user records and the `members` field of group records to -acquire the full list of memberships. The full list can only bet determined by +acquire the full list of memberships. The full list can only be determined by `GetMemberships`, and as mentioned requires merging of these lists of all local services. Result of this is that it can be one service that defines a user A, and another service that defines a group B, and a third service that declares diff --git a/docs/USER_RECORD.md b/docs/USER_RECORD.md index bac0ce1721d..da911d5e73a 100644 --- a/docs/USER_RECORD.md +++ b/docs/USER_RECORD.md @@ -333,7 +333,7 @@ values, which is then inherited by all the user's processes, see [`setrlimit()`](http://man7.org/linux/man-pages/man2/setrlimit.2.html) for more information. -`locked` → A boolean value. If true the user account is locked, the user may +`locked` → A boolean value. If true, the user account is locked, the user may not log in. If this field is missing it should be assumed to be false, i.e. logins are permitted. This field corresponds to the `sp_expire` field of `struct spwd` (i.e. the `/etc/shadow` data for a user) being set to zero or @@ -359,11 +359,11 @@ directory, also containing the `~/.identity` user record; `luks` is a per-user LUKS volume that is mounted as home directory, and `cifs` a home directory mounted from a Windows File Share. The five latter types are primarily used by `systemd-homed` when managing home directories, but may be used if other -managers are used too. If this is not set `classic` is the implied default. +managers are used too. If this is not set, `classic` is the implied default. `diskSize` → An unsigned 64bit integer, indicating the intended home directory disk space in bytes to assign to the user. Depending on the selected storage -type this might be implement differently: for `luks` this is the intended size +type this might be implemented differently: for `luks` this is the intended size of the file system and LUKS volume, while for the others this likely translates to classic file system quota settings. @@ -425,7 +425,7 @@ the top-level directory of the CIFS share is used. `imagePath` → A string with an absolute file system path to the file, directory or block device to use for storage backing the home directory. If the `luks` -storage is used this refers to the loopback file or block device node to store +storage is used, this refers to the loopback file or block device node to store the LUKS volume on. For `fscrypt`, `directory`, `subvolume` this refers to the directory to bind mount as home directory on login. Not defined for `classic` or `cifs`. @@ -465,7 +465,7 @@ relevant when the storage mechanism used is `luks`. referencing the file system UUID the home directory is located in. This is primarily relevant when the storage mechanism used is `luks`. -`luksDiscard` → A boolean. If true and `luks` storage is used controls whether +`luksDiscard` → A boolean. If true and `luks` storage is used, controls whether the loopback block devices, LUKS and the file system on top shall be used in `discard` mode, i.e. erased sectors should always be returned to the underlying storage. If false and `luks` storage is used turns this behavior off. In @@ -579,7 +579,7 @@ against all plugged in security tokens and if there's exactly one matching private key found with it it is used. `fido2HmacCredential` → An array of strings, each with a Base64-encoded FIDO2 -credential ID that shell be used for authentication with FIDO2 devices that +credential ID that shall be used for authentication with FIDO2 devices that implement the `hmac-secret` extension. The salt to pass to the FIDO2 device is found in `fido2HmacSalt`.