Merge pull request #26167 from ldv-alt/docs-fixes

docs: fix a few relatively trivial issues

docs/ARCHITECTURE.md

@@ -44,11 +44,11 @@ on `src/fundamental/` + `src/basic/`, or also on `src/libsystemd/`, or also on
 `src/shared/`.
 
 You might wonder what kind of code belongs where. In general, the rule is that
-code should linked as few times as possible, ideally only once. Thus code that
+code should be linked as few times as possible, ideally only once. Thus code that
 is used by "higher-level" components (e.g. our binaries which are linked to
 `libsystemd-shared-<nnn>.so`), would go to a subdirectory specific to that
 component if it is only used there. If the code is to be shared between
-components, it'd go to `src/shared/`. Shared code that that is used by multiple
+components, it'd go to `src/shared/`. Shared code that is used by multiple
 components that do not link to `libsystemd-shared-<nnn>.so` may live either in
 `src/libsystemd/`, `src/basic/`, or `src/fundamental/`. Any code that is used
 only for EFI goes under `src/boot/efi/`, and `src/fundamental/` if is shared
@@ -99,7 +99,7 @@ setting, it is necessary to support all three input methods:
 unit settings being parsed by common helpers, with the definition in the generator file
 `src/core/load-fragment-gperf.gperf.in`
 2. D-Bus messages are defined and parsed in `src/core/dbus-*.c`
-3. `systemd-run` and `systemctl set-property` do client-side parsing and translating into
+3. `systemd-run` and `systemctl set-property` do client-side parsing and translation into
 D-Bus messages in `src/shared/bus-unit-util.c`
 
 So that they are exercised by the fuzzing CI, new unit settings should also be listed in the

docs/AUTOMATIC_BOOT_ASSESSMENT.md

@@ -15,7 +15,7 @@ many attempts should be made to boot it. This document describes how systemd
 implements this scheme.
 
 The many different components involved in the implementation may be used
-independently and in combination with other software to for example support
+independently and in combination with other software to, for example, support
 other boot loaders or take actions outside of the boot loader.
 
 Here's a brief overview of the complete set of components:
@@ -93,10 +93,10 @@ Here's an example walkthrough of how this all fits together.
    After the rename completed, the entry is booted as usual.
 
 4. Let's say this attempt to boot fails. On the following boot the boot loader
-   will hence see the `+2-1` tag in the name, and hence rename the entry file to
+   will hence see the `+2-1` tag in the name, and will hence rename the entry file to
    `4.14.11-300.fc27.x86_64+1-2.conf`, and boot it.
 
-5. Let's say the boot fails again. On the subsequent boot the loader hence will
+5. Let's say the boot fails again. On the subsequent boot the loader will hence
    see the `+1-2` tag, and rename the file to
    `4.14.11-300.fc27.x86_64+0-3.conf` and boot it.
 
@@ -200,7 +200,7 @@ are a couple of recommendations.
 
    Such unit would be typically wanted (or required) by one of the
    [`bootup`](https://www.freedesktop.org/software/systemd/man/bootup.html) targets,
-   for example `multi-user.target`. To avoid potential loops due to conflicting
+   for example, `multi-user.target`. To avoid potential loops due to conflicting
    [default dependencies](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#Default%20Dependencies)
    ordering, it is recommended to also add an explicit dependency (e.g.
    `After=multi-user.target`) to the unit. This overrides the implicit ordering

docs/BUILDING_IMAGES.md

@@ -32,7 +32,7 @@ boot. For that it's essential to:
    is not reset, and carries a valid ID every instance of the system will come
    up with the same ID and that will likely lead to problems sooner or later,
    as many network-visible identifiers are commonly derived from the machine
-   ID, for example IPv6 addresses or transient MAC addresses.
+   ID, for example, IPv6 addresses or transient MAC addresses.
 
 2. Remove the `/var/lib/systemd/random-seed` file (see
    [`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)),
@@ -83,7 +83,7 @@ which can be a freely chosen string to use for identifying the boot menu
 resources of the OS. If not configured explicitly it defaults to the machine
 ID. The file `/etc/kernel/entry-token` may be used to configure this string
 explicitly. Thus, golden image builders should write a suitable identifier into
-this file, for example the `IMAGE_ID=` or `ID=` field from
+this file, for example, the `IMAGE_ID=` or `ID=` field from
 [`/etc/os-release`](https://www.freedesktop.org/software/systemd/man/os-release.html)
 (also see below). It is recommended to do this before the `kernel-install`
 functionality is invoked (i.e. before the package manager is used to install
@@ -117,7 +117,7 @@ Specifically, the following mechanisms are in place:
 
 4. The
    [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.service.html)
-   will component automatically populate `/etc/passwd` and `/etc/group` on
+   component will automatically populate `/etc/passwd` and `/etc/group` on
    first boot with further necessary system users.
 
 5. The
@@ -161,7 +161,7 @@ the OS should take possession of the backing storage as necessary, dynamically
 using available space. Specifically:
 
 1. Additional partitions should be created, that make no sense to ship
-   pre-built in the image. For example `/tmp/` or `/home/` partitions, or even
+   pre-built in the image. For example, `/tmp/` or `/home/` partitions, or even
    `/var/` or the root file system (see above).
 
 2. Additional partitions should be created that shall function as A/B

docs/CGROUP_DELEGATION.md

@@ -78,7 +78,7 @@ Note that cgroup v1 is currently the most deployed implementation, even though
 it's semantically broken in many ways, and in many cases doesn't actually do
 what people think it does. cgroup v2 is where things are going, and most new
 kernel features in this area are only added to cgroup v2, and not cgroup v1
-anymore. For example cgroup v2 provides proper cgroup-empty notifications, has
+anymore. For example, cgroup v2 provides proper cgroup-empty notifications, has
 support for all kinds of per-cgroup BPF magic, supports secure delegation of
 cgroup trees to less privileged processes and so on, which all are not
 available on cgroup v1.

docs/CODE_QUALITY.md

@@ -23,7 +23,7 @@ available functionality:
 
 2. Use `./test/run-integration-tests.sh` to run the full integration test
    suite. This will build OS images with a number of integration tests and run
-   them in nspawn and qemu. Requires root.
+   them using `systemd-nspawn` and `qemu`. Requires root.
 
 3. Use `./coccinelle/run-coccinelle.sh` to run all
    [Coccinelle](http://coccinelle.lip6.fr/) semantic patch scripts we ship. The

docs/CODING_STYLE.md

@@ -208,7 +208,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   variables if you are sure that thread-safety doesn't matter in your
   case. Alternatively, consider using TLS, which is pretty easy to use with
   gcc's `thread_local` concept. It's also OK to store data that is inherently
-  global in global variables, for example data parsed from command lines, see
+  global in global variables, for example, data parsed from command lines, see
   below.
 
 - Our focus is on the GNU libc (glibc), not any other libcs. If other libcs are
@@ -604,7 +604,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   i.e.  file system objects that are supposed to be regular files whose paths
   were specified by the user and hence might actually refer to other types of
   file system objects. This is a good idea so that we don't end up blocking on
-  'strange' file nodes, for example if the user pointed us to a FIFO or device
+  'strange' file nodes, for example, if the user pointed us to a FIFO or device
   node which may block when opening. Moreover even for actual regular files
   `O_NONBLOCK` has a benefit: it bypasses any mandatory lock that might be in
   effect on the regular file. If in doubt consider turning off `O_NONBLOCK`
@@ -712,7 +712,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
 ## Committing to git
 
 - Commit message subject lines should be prefixed with an appropriate component
-  name of some kind. For example "journal: ", "nspawn: " and so on.
+  name of some kind. For example, "journal: ", "nspawn: " and so on.
 
 - Do not use "Signed-Off-By:" in your commit messages. That's a kernel thing we
   don't do in the systemd project.
@@ -730,7 +730,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
   hard. Moreover, while we rely heavily on GitHub's project management
   infrastructure we'd like to keep everything that can reasonably be kept in
   the git repository itself in the git repository, so that we can theoretically
-  move things elswhere with the least effort possible.
+  move things elsewhere with the least effort possible.
 
 - It's OK to reference GitHub PRs, GitHub issues and git commits from code
   comments. Cross-referencing code, issues, and documentation is a good thing.

docs/CONTAINER_INTERFACE.md

@@ -210,7 +210,7 @@ manager, please consider supporting the following interfaces.
    container name the external side `ve-` + the container name.
 
 3. It is recommended to configure stable MAC addresses for container `veth`
-   devices, for example hashed out of the container names. That way it is more
+   devices, for example, hashed out of the container names. That way it is more
    likely that DHCP and IPv4LL will acquire stable addresses.
 
 ## The `/run/host/` Hierarchy
@@ -389,7 +389,7 @@ everybody. However, that's a systemd-specific interface and other init systems
 are unlikely to do the same.
 
 Note that it is our intention to make systemd systems work flawlessly and
-out-of-the-box in containers. In fact we are interested to ensure that the same
+out-of-the-box in containers. In fact, we are interested to ensure that the same
 OS image can be booted on a bare system, in a VM and in a container, and behave
 correctly each time. If you notice that some component in systemd does not work
 in a container as it should, even though the container manager implements

docs/CONTRIBUTING.md

@@ -41,9 +41,9 @@ See [reporting of security vulnerabilities](SECURITY.md).
 * After you have pushed a new version, add a comment explaining the latest changes. If you are a member of the systemd project on GitHub, remove the `reviewed/needs-rework`/`ci-fails/needs-rework`/`needs-rebase` labels.
 * If you are copying existing code from another source (eg: a compat header), please make sure the license is compatible with `LGPL-2.1-or-later`. If the license is not `LGPL-2.1-or-later`, please add a note to [`LICENSES/README.md`](https://github.com/systemd/systemd/blob/main/LICENSES/README.md).
 * If the pull request stalls without review, post a ping in a comment after some time has passed. We are always short on reviewer time, and pull requests which haven't seen any recent activity can be easily forgotten.
-* Github will automatically add the please-review label when a pull request is opened or updated. If you need
+* Github will automatically add the `please-review` label when a pull request is opened or updated. If you need
 more information after a review, you can comment `/please-review` on the pull request to have Github add the
-please-review to the pull request.
+`please-review` label to the pull request.
 
 ## Reviewing Pull Requests
 

docs/CREDENTIALS.md

@@ -162,7 +162,7 @@ When invoked from service context, `systemd-creds` passed without further
 parameters will list passed credentials. The `systemd-creds cat xyz` command
 may be used to write the contents of credential `xyz` to standard output. If
 these calls are combined with the `--system` switch credentials passed to the
-system as a whole are shown, instead of the those passed to the service the
+system as a whole are shown, instead of those passed to the service the
 command is invoked from.
 
 Example use:
@@ -179,17 +179,17 @@ via `systemd-creds cat`.
 
 Credentials are supposed to be useful for carrying sensitive information, such
 as cryptographic key material. For this kind of data (symmetric) encryption and
-authentication is provided to make storage of the data at rest safer. The data
+authentication are provided to make storage of the data at rest safer. The data
 may be encrypted and authenticated with AES256-GCM. The encryption key can
 either be one derived from the local TPM2 device, or one stored in
 `/var/lib/systemd/credential.secret`, or a combination of both. If a TPM2
-device is available and `/var/` resides on persistent storage the default
+device is available and `/var/` resides on a persistent storage, the default
 behaviour is to use the combination of both for encryption, thus ensuring that
 credentials protected this way can only be decrypted and validated on the
 local hardware and OS installation. Encrypted credentials stored on disk thus
 cannot be decrypted without access to the TPM2 chip and the aforementioned key
 file `/var/lib/systemd/credential.secret`. Moreover, credentials cannot be
-prepared on another machine than the local one.
+prepared on a machine other than the local one.
 
 The `systemd-creds` tool provides the commands `encrypt` and `decrypt` to
 encrypt and decrypt/authenticate credentials. Example:
@@ -345,7 +345,7 @@ Various services shipped with `systemd` consume credentials for tweaking behavio
   `passwd.plaintext-password.<username>` and `passwd.shell.<username>` to
   configure the password (either in UNIX hashed form, or plaintext) or shell of
   system users created. Replace `<username>` with the system user of your
-  choice, for example `root`.
+  choice, for example, `root`.
 
 * [`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html)
   will look for the credentials `firstboot.locale`, `firstboot.locale-messages`,
@@ -442,5 +442,5 @@ hence a great place to store credentials to load on the system.
 ## Conditionalizing Services
 
 Sometimes it makes sense to conditionalize system services and invoke them only
-if the right system credential is passed to the system. use the
+if the right system credential is passed to the system. Use the
 `ConditionCredential=` and `AssertCredential=` unit file settings for that.

docs/DISTRO_PORTING.md

@@ -85,7 +85,7 @@ instead install your own.
 
 ## Contributing Upstream
 
-We generally do no longer accept distribution-specific patches to
+We generally no longer accept distribution-specific patches to
 systemd upstream. If you have to make changes to systemd's source code
 to make it work on your distribution, unless your code is generic
 enough to be generally useful, we are unlikely to merge it. Please

docs/PORTABILITY_AND_STABILITY.md

@@ -155,7 +155,7 @@ without communicating with the `systemd` process:
 `systemd-sysusers`.
 
 Many other programs support operation without the system manager except when
-the specific functionality requires such communication. For example
+the specific functionality requires such communication. For example,
 `journalctl` operates almost independently, but will query the boot id when
 `--boot` option is used; it also requires `systemd-journald` (and thus
 `systemd`) to be running for options like `--flush` and `--sync`.

docs/PORTABLE_SERVICES.md

@@ -95,7 +95,7 @@ This command does the following:
    image, and looks for all included unit files.
 
 2. It copies out all unit files with a suffix of `.service`, `.socket`,
-   `.target`, `.timer` and `.path`. whose name begins with the image's name
+   `.target`, `.timer` and `.path`, whose name begins with the image's name
    (with `.raw` removed), truncated at the first underscore if there is one.
    This prefix name generated from the image name must be followed by a ".",
    "-" or "@" character in the unit name. Or in other words, given the image
@@ -303,7 +303,7 @@ Docker would do it, as these are regular system services they aren't run as PID
 
 If services shipped with this mechanism shall be able to access host resources
 (such as files or AF_UNIX sockets for IPC), use the normal `BindPaths=` and
-`BindReadOnlyPaths=` settings in unit files to mount them in. In fact the
+`BindReadOnlyPaths=` settings in unit files to mount them in. In fact, the
 `default` profile mentioned above makes use of this to ensure
 `/etc/resolv.conf`, the D-Bus system bus socket or write access to the logging
 subsystem are available to the service.
@@ -329,7 +329,7 @@ units shipped with the OS itself as for attached portable services.
 ## Immutable images with local data
 
 It's a good idea to keep portable service images read-only during normal
-operation. In fact all but the `trusted` profile will default to this kind of
+operation. In fact, all but the `trusted` profile will default to this kind of
 behaviour, by setting the `ProtectSystem=strict` option. In this case writable
 service data may be placed on the host file system. Use `StateDirectory=` in
 the unit files to enable such behaviour and add a local data directory to the

docs/PORTING_TO_NEW_ARCHITECTURES.md

@@ -34,7 +34,7 @@ architecture.
    variable logic in `meson.build` to be set to the right architecture string
    as defined by the UEFI specification. (This ensures that `systemd-boot` will
    be built as the appropriately named `BOOT<arch>.EFI` binary.) Also, if your
-   architecture uses a special boot protocol for the Linux kernel make sure to
+   architecture uses a special boot protocol for the Linux kernel, make sure to
    implement it in `src/boot/efi/linux*.c`, so that the `systemd-stub` EFI stub
    can work.
 
@@ -54,5 +54,5 @@ architecture.
    `/usr/` mounted in.
 
 7. If your architecture supports VM virtualization and provides CPU opcodes
-   similar to x86' CPUID consider adding native support for detecting VMs this
+   similar to x86' CPUID, consider adding native support for detecting VMs this
    way to `src/basic/virt.c`.

docs/RANDOM_SEEDS.md

@@ -26,23 +26,23 @@ The Linux kernel provides three relevant userspace APIs to request random data
 from the kernel's entropy pool:
 
 * The [`getrandom()`](https://man7.org/linux/man-pages/man2/getrandom.2.html)
-  system call with its `flags` parameter set to 0. If invoked the calling
+  system call with its `flags` parameter set to 0. If invoked, the calling
   program will synchronously block until the random pool is fully initialized
   and the requested bytes can be provided.
 
 * The `getrandom()` system call with its `flags` parameter set to
-  `GRND_NONBLOCK`. If invoked the request for random bytes will fail if the
+  `GRND_NONBLOCK`. If invoked, the request for random bytes will fail if the
   pool is not initialized yet.
 
 * Reading from the
   [`/dev/urandom`](https://man7.org/linux/man-pages/man4/urandom.4.html)
   pseudo-device will always return random bytes immediately, even if the pool
   is not initialized. The provided random bytes will be of low quality in this
-  case however. Moreover the kernel will log about all programs using this
+  case however. Moreover, the kernel will log about all programs using this
   interface in this state, and which thus potentially rely on an uninitialized
   entropy pool.
 
-(Strictly speaking there are more APIs, for example `/dev/random`, but these
+(Strictly speaking, there are more APIs, for example `/dev/random`, but these
 should not be used by almost any application and hence aren't mentioned here.)
 
 Note that the time it takes to initialize the random pool may differ between
@@ -107,7 +107,7 @@ encrypted storage which might need random numbers. systemd itself requires
 random numbers as well, including for the following uses:
 
 * systemd assigns 'invocation' UUIDs to all services it invokes that uniquely
-  identify each invocation. This is useful retain a global handle on a specific
+  identify each invocation. This is useful to retain a global handle on a specific
   service invocation and relate it to other data. For example, log data
   collected by the journal usually includes the invocation UUID and thus the
   runtime context the service manager maintains can be neatly matched up with

docs/TESTING_WITH_SANITIZERS.md

@@ -31,11 +31,11 @@ Note that this will only work with a recent version of mkosi (>= 14 or by runnin
 
 ## gcc
 gcc compiles in sanitizer libraries dynamically by default, so you need to get
-the shared libraries first - on Fedora these are shipped as a separate packages
+the shared libraries first - on Fedora these are shipped as separate packages
 (`libasan` for Address Sanitizer and `libubsan` for Undefined Behavior Sanitizer).
 
 The compilation itself is then a matter of simply adding `-Db_sanitize=address,undefined`
-to `meson`. That's it - following executions of `meson test` and integrations tests
+to `meson`. That's it - following executions of `meson test` and integration tests
 under `test/` subdirectory will run with sanitizers enabled. However, to get
 truly useful results, you should tweak the runtime configuration of respective
 sanitizers; e.g. in systemd we set the following environment variables:

docs/USERDB_AND_DESKTOPS.md

@@ -152,7 +152,7 @@ users registered in `/etc/passwd` or LDAP to users managed by
 ## Future Additions
 
 JSON user/group records are extensible, hence we can easily add any additional
-fields desktop environments require. For example pattern-based authentication
+fields desktop environments require. For example, pattern-based authentication
 is likely very useful on touch-based devices, and the user records should hence
 learn them natively. Fields for other authentication mechanisms, such as
 fingerprint authentication should be provided as well, eventually.

docs/USER_GROUP_API.md

@@ -129,7 +129,7 @@ interface. Specifically:
    `systemd-machined.service` and provides records for the users and groups used
    by local containers that use user namespacing.
 
-Other projects are invited to implement these services too. For example it
+Other projects are invited to implement these services too. For example, it
 would make sense for LDAP/ActiveDirectory projects to implement these
 interfaces, which would provide them a way to do per-user resource management
 enforced by systemd and defined directly in LDAP directories.

docs/USER_NAMES.md

@@ -29,7 +29,7 @@ Generally, the same rules apply for user as for group names.
   hyphen](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282),
   with the restriction that hyphen is not allowed as first character of the
   user name. Interestingly no size limit is declared, i.e. in neither
-  direction, meaning that strictly speaking according to POSIX both the empty
+  direction, meaning that strictly speaking, according to POSIX, both the empty
   string is a valid user name as well as a string of gigabytes in length.
 
 * Debian/Ubuntu based systems enforce the regular expression
@@ -151,7 +151,7 @@ user/group names accepted by the strict rules are also accepted by the relaxed
 rules, but not vice versa.
 
 Note that this relaxed mode does not refuse a couple of very questionable
-syntaxes. For example it permits a leading or embedded period. A leading period
+syntaxes. For example, it permits a leading or embedded period. A leading period
 is problematic because the matching home directory would typically be hidden
 from the user's/administrator's view. An embedded period is problematic since
 it creates ambiguity in traditional `chown` syntax (which is still accepted

man/systemd-system.conf.xml

@@ -464,7 +464,7 @@
         of slice units. Defaults to 15% of the minimum of <varname>kernel.pid_max=</varname>, <varname>kernel.threads-max=</varname>
         and root cgroup <varname>pids.max</varname>.
         Kernel has a default value for <varname>kernel.pid_max=</varname> and an algorithm of counting in case of more than 32 cores.
-        For example with the default <varname>kernel.pid_max=</varname>, <varname>DefaultTasksMax=</varname> defaults to 4915,
+        For example, with the default <varname>kernel.pid_max=</varname>, <varname>DefaultTasksMax=</varname> defaults to 4915,
         but might be greater in other systems or smaller in OS containers.</para></listitem>
       </varlistentry>
 

man/systemd.unit.xml

@@ -2329,7 +2329,7 @@ PrivateTmp=yes</programlisting>
       <title>Top level drop-ins with template units</title>
 
       <para>Top level per-type drop-ins can be used to change some aspect of
-      all units of a particular type. For example by creating the
+      all units of a particular type. For example, by creating the
       <filename index='false'>/etc/systemd/system/service.d/</filename>
       directory with a drop-in file, the contents of the drop-in file can be
       applied to all service units. We can take this further by having the