docs: fix spelling and use better formatting/wording in places

docs/.custom_wordlist.txt

@@ -1 +1,16 @@
 # Leave a blank line at the end of this file to support concatenation
+backoff
+boolean
+Drepper
+idempotently
+liveness
+mkdir
+ns
+runit
+replan
+subcommands
+supervisord
+systemd
+UIDs
+Ulrich
+Utils

docs/explanation/api-and-clients.md

@@ -1,6 +1,6 @@
 # API and clients
 
-The Pebble daemon exposes an API (HTTP over a unix socket) to allow remote clients to interact with the daemon. It can start and stop services, add configuration layers to the plan, and so on.
+The Pebble daemon exposes an API (HTTP over a Unix socket) to allow remote clients to interact with the daemon. It can start and stop services, add configuration layers to the plan, and so on.
 
 If `pebble run` is started with the `--http <address>` option, Pebble also exposes open-access HTTP endpoints using the given TCP address (see {ref}`api-access-levels` below).
 
@@ -52,7 +52,7 @@ Currently the supported authentication types are:
 - `local`: a local user ID determined using peer credentials.
 - `basic`: HTTP basic authentication.
 
-An example admin identity named "bob" with `local` type is shown below:
+An example admin identity named `bob` with `local` type is shown below:
 
 ```yaml
 identities:
@@ -62,7 +62,7 @@ identities:
             user-id: 42
 ```
 
-An example identity named "alice" with `basic` type and `metrics` access level is shown below:
+An example identity named `alice` with `basic` type and `metrics` access level is shown below:
 
 ```yaml
 identities:

docs/explanation/general-model.md

@@ -1,5 +1,5 @@
 # General model
 
-Pebble is organized as a single binary that works as a daemon and also as a client to itself. When the daemon runs it loads its own configuration from the `$PEBBLE` directory, as defined in the environment, and also records in that same directory its state and unix sockets for communication. If that variable is not defined, Pebble will attempt to look for its configuration from a default system-level setup at `/var/lib/pebble/default`. Using that directory is encouraged for whole-system setup such as when using Pebble to control services in a container.
+Pebble is organized as a single binary that works as a daemon and also as a client to itself. When the daemon runs it loads its own configuration from the `$PEBBLE` directory, as defined in the environment, and also records in that same directory its state and Unix sockets for communication. If that variable is not defined, Pebble will attempt to look for its configuration from a default system-level setup at `/var/lib/pebble/default`. Using that directory is encouraged for whole-system setup such as when using Pebble to control services in a container.
 
 The `$PEBBLE` directory must contain a `layers/` subdirectory that holds a stack of configuration files with names similar to `001-base-layer.yaml`, where the digits define the order of the layer and the following label uniquely identifies it. Each layer in the stack sits above the former one, and has the chance to improve or redefine the service configuration as desired.

docs/explanation/security.md

@@ -49,4 +49,4 @@ Our intention is that projects that build on Pebble can [override how TLS connec
 
 ### FIPS 140
 
-This project also distributes [FIPS 140](https://en.wikipedia.org/wiki/FIPS_140)-compliant builds of Pebble: the source code is in the `fips` branch and there's the `fips` track for the official [`pebble` snap](https://snapcraft.io/pebble). Refer to [HACKING.md](https://github.com/canonical/pebble/blob/fips/HACKING.md#fips-140-changes) in the `fips` branch for the list of limiations in the FIPS builds.
+This project also distributes [FIPS 140](https://en.wikipedia.org/wiki/FIPS_140)-compliant builds of Pebble: the source code is in the `fips` branch and there's the `fips` track for the official [`pebble` snap](https://snapcraft.io/pebble). Refer to [HACKING.md](https://github.com/canonical/pebble/blob/fips/HACKING.md#fips-140-changes) in the `fips` branch for the list of limitations in the FIPS builds.

docs/how-to/manage-identities.md

@@ -10,7 +10,7 @@ By default any UID (user ID) connected to the API socket is a `read` user; UID 0
 
 ## Add new identities
 
-To extend access to Pebble's API to additional users, add named identities using the [`add-identities`](#reference_pebble_add-identities_command) command with a YAML file configuring the details. For example, to add a new admin "bob" with UID 42 and a new read user "alice" with UID 2000, prepare this file:
+To extend access to Pebble's API to additional users, add named identities using the [`add-identities`](#reference_pebble_add-identities_command) command with a YAML file configuring the details. For example, to add a new admin `bob` with UID 42 and a new read user `alice` with UID 2000, prepare this file:
 
 ```yaml
 # idents-add.yaml
@@ -37,7 +37,7 @@ Added 2 new identities.
 
 ## Remove identities
 
-To remove existing identities, use [`remove-identities`](#reference_pebble_remove-identities_command) with a YAML file that has a `null` value for each identity you want to remove. For example, to remove "alice", prepare this file:
+To remove existing identities, use [`remove-identities`](#reference_pebble_remove-identities_command) with a YAML file that has a `null` value for each identity you want to remove. For example, to remove `alice`, prepare this file:
 
 ```yaml
 # idents-remove.yaml
@@ -75,7 +75,7 @@ pebble update-identities --from idents-update.yaml
 Updated 1 identity.
 ```
 
-You can use the `--replace` flag to idempotently add or update (or even remove) identities, whether or not they exist. The replace option is useful in automated scripts. For example, to update "bob", add "alice", and remove "mallory" (if it exists), prepare this file:
+You can use the `--replace` flag to idempotently add or update (or even remove) identities, whether or not they exist. The replace option is useful in automated scripts. For example, to update `bob`, add `alice`, and remove `mallory` (if it exists), prepare this file:
 
 ```yaml
 # idents-replace.yaml

docs/index.md

@@ -14,7 +14,7 @@ explanation/index
 
 It helps you orchestrate a set of local processes as an organized set. It resembles well-known tools such as _supervisord_, _runit_, or _s6_, in that it can easily manage non-system processes independently from the system services. However, it was designed with unique features such as layered configuration and an HTTP API that help with more specific use cases.
 
-If you need a way to manage one or more services in a container, or as a non-root user on a machine, Pebble might be for you. It handles service logs, service dependencies, and allows you to set up ongoing health checks. Plus, it has an "HTTP over unix socket" API for all operations, with simple UID-based access control.
+If you need a way to manage one or more services in a container, or as a non-root user on a machine, Pebble might be for you. It handles service logs, service dependencies, and allows you to set up ongoing health checks. Plus, it has an "HTTP over Unix socket" API for all operations, with simple UID-based access control.
 
 Pebble is useful for developers who are building {external+operator:ref}`Juju charms on Kubernetes <from-zero-to-hero-write-your-first-kubernetes-charm>`, creating {external+rockcraft:ref}`Rock <explanation-rocks>` or Docker images, or orchestrating services in the virtual machine.
 

docs/reference/api.md

@@ -77,7 +77,7 @@ Some `GET` requests take optional query parameters for configuring or filterin
 
 All data sent to the API in `POST` bodies and all response data from the API is in JSON format. Requests should have a `Content-Type: application/json` header.
 
-There are two main types of requests: synchronous ("sync"), and asynchronous ("async") for operations that can take some time to execute. Synchronous responses have the following structure:
+There are two main types of requests: synchronous (`sync`), and asynchronous (`async`) for operations that can take some time to execute. Synchronous responses have the following structure:
 
 ```json
 {

docs/reference/cli-commands.md

@@ -218,7 +218,7 @@ pebble exec pg_dump mydb
 ...
 ```
 
-The exec feature uses WebSockets under the hood, and allows you to stream stdin to the process, as well as stream stdout and stderr back. When running `pebble exec`, you can specify the working directory to run in (`-w`), environment variables to set (`--env`), and the user and group to run as (`--uid`/`--user` and `--gid`/`--group`).
+The exec feature uses WebSockets under the hood, and allows you to stream `stdin` to the process, as well as stream `stdout` and `stderr` back. When running `pebble exec`, you can specify the working directory to run in (`-w`), environment variables to set (`--env`), and the user and group to run as (`--uid`/`--user` and `--gid`/`--group`).
 
 You can also apply a timeout with `--timeout`, for example:
 
@@ -361,7 +361,7 @@ The identity command shows details for a single identity in YAML format.
 (reference_pebble_logs_command)=
 ## logs
 
-The Pebble daemon's service manager stores the most recent stdout and stderr from each service, using a 100KB ring buffer per service. Each log line is prefixed with an RFC-3339 timestamp and the `[service-name]` in square brackets.
+The Pebble daemon's service manager stores the most recent `stdout` and `stderr` from each service, using a 100KB ring buffer per service. Each log line is prefixed with an RFC-3339 timestamp and the `[service-name]` in square brackets.
 
 Logs are viewable via the logs API or using `pebble logs`:
 
@@ -419,7 +419,7 @@ pebble logs --format=json
 {"time":"2022-11-14T01:39:13.889Z","service":"srv1","message":"Log 1 from srv1"}
 ```
 
-If you want to also write service logs to Pebble's own stdout, run the daemon with `--verbose`:
+If you want to also write service logs to Pebble's own `stdout`, run the daemon with `--verbose`:
 
 ```{terminal}
 pebble run --verbose
@@ -970,7 +970,7 @@ More ways to run the daemon:
     pebble run --args myservice --verbose --foo "multi str arg"
     ```
 
-* Use args terminator to pass `--hold` to Pebble at the end of the line:
+* Use the argument terminator `;` to pass `--hold` to Pebble:
 
     ```bash
     pebble run --args myservice --verbose \; --hold

docs/reference/environment-variables.md

@@ -14,7 +14,7 @@ This will only copy the contents if the target directory, `$PEBBLE`, is empty.
 
 ## PEBBLE_DEBUG
 
-If set to "1", debug logs will be printed to stderr.
+If set to "1", debug logs will be printed to `stderr`.
 
 ## PEBBLE_PERSIST
 
@@ -26,7 +26,7 @@ Pebble socket path. Defaults to `$PEBBLE/.pebble.socket` if not specified, or `/
 
 ## PEBBLE_VERBOSE
 
-If set to "1", the Pebble daemon writes service logs to stdout.
+If set to "1", the Pebble daemon writes service logs to `stdout`.
 
 For `pebble run`, either `PEBBLE_VERBOSE=1` or the `--verbose` flag turns on verbose logging, with the command line flag overriding the environment variable.
 

docs/reference/identities.md

@@ -29,7 +29,7 @@ identities:
             password: <password hash>
 ```
 
-For example, a local identity named "bob" with UID 42 that is granted `admin` access would be defined as follows:
+For example, a local identity named `bob` with UID 42 that is granted `admin` access would be defined as follows:
 
 ```yaml
 identities:
@@ -39,15 +39,14 @@ identities:
             user-id: 42
 ```
 
-For another example, a basic identity named "alice" that is granted `metrics` access would be defined as follows:
+For another example, a basic identity named `alice` that is granted `metrics` access would be defined as follows:
 
 ```yaml
 identities:
     alice:
         access: metrics
         basic:
-            # The password is hashed using sha512-crypt, as generated by "openssl passwd -6".
             password: <password hash>
 ```
 
-The password is hashed using sha512-crypt, as generated by "openssl passwd -6".
+The password is hashed using sha512-crypt, as generated by `openssl passwd -6`.

docs/reference/index.md

@@ -2,9 +2,9 @@
 
 These guides provide technical information about Pebble.
 
-% COMMENT: This toctree is for the navigation sidebar only
-%          Use an alphabetical listing of pages in the toctree
-%          For each page, make sure there's also a link in a section below
+% COMMENT: This tree is for the navigation sidebar only.
+%          Use an alphabetical listing of pages in the tree.
+%          For each page, make sure there's also a link in a section below.
 
 ```{toctree}
 :hidden:
@@ -24,7 +24,7 @@ Service auto-restart <service-auto-restart>
 ```
 
 
-% COMMENT: The first few pages are presented in a more logical reading order
+% COMMENT: The first few pages are presented in a more logical reading order.
 
 
 ## Layers

docs/reference/log-forwarding.md

@@ -22,7 +22,7 @@ Required configuration:
 
 - `override`: How this log target definition is combined with other pre-existing definitions with the same name in the plan. Supported values are `merge` and `replace`.
 - `type`: The type of log target. Supported types are `loki`, `opentelemetry` and `syslog`.
-- `location`: The URL of the remote log target. For Loki, this needs to be the fully-qualified URL of the push API, including the API endpoint; use the format `http://<host-or-ip>:3100/loki/api/v1/push`. For OpenTelemetry, include the TCP port (normally 4318) without the API endpoint, for example: `http://<host-or-ip>:4318`. For Syslog, this needs to be either `tcp://<host-or-ip>:<port>` or `udp://<host-or-ip>:<port>`.
+- `location`: The URL of the remote log target. For Loki, this needs to be the fully-qualified URL of the push API, including the API endpoint; use the format `http://<host-or-ip>:3100/loki/api/v1/push`. For OpenTelemetry, include the TCP port (normally 4318) without the API endpoint, for example: `http://<host-or-ip>:4318`. For `syslog`, this needs to be either `tcp://<host-or-ip>:<port>` or `udp://<host-or-ip>:<port>`.
 
 Optional configuration: