Additional documentation reference refactoring (#942).

docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md

@@ -23,6 +23,9 @@ or an offline server or a low battery—and exit gracefully? That's where the
 concept of "soft failure" come in.
 
 
+<a id="caveats-and-details"></a>
+
+
 ## Soft failure command hooks
 
 This feature leverages [borgmatic command
@@ -32,7 +35,7 @@ test in the form of a borgmatic command hook to see if backups should proceed or
 not.
 
 The way the test works is that if any of your hook commands return a special
-exit status of 75, that indicates to borgmatic that it's a temporary failure,
+exit status of 75, that indicates to borgmatic that it's a temporary failure
 and borgmatic should skip all subsequent actions for the current repository.
 
 If you return any status besides 75, then it's a standard success or error.
@@ -114,33 +117,6 @@ commands:
 
 Writing the battery script is left as an exercise to the reader.
 
-
-## Caveats and details
-
-There are some caveats you should be aware of with this feature.
-
- * You'll generally want to put a soft failure command in a `before` command
-   hook, so as to gate whether the backup action occurs. While a soft failure is
-   also supported in an `after` command hook, returning a soft failure there
-   won't prevent any actions from occurring, because they've already occurred!
-   Similarly, you can return a soft failure from an `error` command hook, but at
-   that point it's too late to prevent the error.
- * Returning a soft failure does prevent further commands in the same hook from
-   executing. So, like a standard error, it is an "early out." Unlike a standard
-   error, borgmatic does not display it in angry red text or consider it a
-   failure.
- * <span class="minilink minilink-addedin">New in version 1.9.0</span> Soft
-   failures in `action` or `before_*` command hooks only skip the current
-   repository rather than all repositories in a configuration file.
- * If you're writing a soft failure script that you want to vary based on the
-   current repository, for instance so you can have multiple repositories in a
-   single configuration file, have a look at [command hook variable
-   interpolation](https://torsion.org/borgmatic/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation).
-   And there's always still the option of putting anything that you don't want
-   soft-failed (like always-online cloud backups) in separate configuration
-   files from your soft-failing repositories.
- * The soft failure doesn't have to test anything related to a repository. You
-   can even perform a test that individual source directories are mounted and
-   available. Use your imagination!
- * Soft failures are not currently implemented for `everything`,
-   `before_everything`, or `after_everything` command hooks.
+See the [soft failure
+documentation](https://torsion.org/borgmatic/reference/configuration/command-hooks/#soft-failure)
+for additional details.

docs/how-to/develop-on-borgmatic.md

@@ -111,6 +111,10 @@ them:
 tox -e spell
 ```
 
+See the [code style
+documentation](https://torsion.org/borgmatic/reference/source-code/#code-style)
+for more specifics about borgmatic's own code style.
+
 
 ### End-to-end tests
 
@@ -155,36 +159,6 @@ Then you'll be able to run end-to-end tests as per normal, and the test script
 will automatically use your non-root Podman socket instead of a Docker socket.
 
 
-## Code style
-
-When writing code for borgmatic, start with [PEP
-8](https://www.python.org/dev/peps/pep-0008/). But then, apply the following
-deviations from it:
-
- * For strings, prefer single quotes over double quotes.
- * Limit all lines to a maximum of 100 characters.
- * Use trailing commas within multiline values or argument lists.
- * For multiline constructs, put opening and closing delimiters on lines
-   separate from their contents.
- * Within multiline constructs, use standard four-space indentation. Don't align
-   indentation with an opening delimiter.
- * In general, spell out words in variable names instead of shortening them.
-   So, think `index` instead of `idx`. There are some notable exceptions to
-   this though (like `config`).
- * Favor blank lines around logical code groupings, `if` statements,
-   `return`s, etc. Readability is more important than packing code tightly.
- * Import fully qualified Python modules instead of importing individual
-   functions, classes, or constants. E.g., do `import os.path` instead of
-   `from os import path`. (Some exceptions to this are made in tests.)
- * Only use classes and OOP as a last resort, such as when integrating with
-   Python libraries that require it.
- * Prefer functional code where it makes sense, e.g. when constructing a
-   command (to subsequently execute imperatively).
-
-Since borgmatic uses Ruff for code lining and formatting, many other code style
-requirements are also enforced when running automated tests.
-
-
 ## Continuous integration
 
 Each commit to

docs/how-to/run-arbitrary-borg-commands.md

@@ -26,7 +26,7 @@ arguments:
  * verbosity
 
 
-### borg action
+## borg action
 
 <span class="minilink minilink-addedin">New in version 1.5.15</span> The way
 you run Borg with borgmatic is via the `borg` action. Here's a simple example:
@@ -43,13 +43,10 @@ be preferred though for most uses.)
 You can also specify Borg options for relevant commands. For instance:
 
 ```bash
-borgmatic borg repo-list --short
+borgmatic borg list --short
 ```
 
-(No borgmatic `repo-list` action? Try `rlist` or `list` instead or upgrade
-borgmatic!)
-
-This runs Borg's `repo-list` command once on each configured borgmatic
+This runs Borg's `list` command once on each configured borgmatic
 repository.
 
 What if you only want to run Borg on a single configured borgmatic repository
@@ -76,7 +73,7 @@ the right place (which didn't always work). So your command-line in these
 older versions didn't support the `::`
 
 
-### Specifying an archive
+## Specifying an archive
 
 For borg commands that expect an archive name, you have a few approaches.
 Here's one:
@@ -117,7 +114,7 @@ borgmatic borg --archive latest list '$ARCHIVE'
 borgmatic borg list your-actual-archive-name
 ```
 
-### Limitations
+## Limitations
 
 borgmatic's `borg` action is not without limitations:
 

docs/reference/configuration/command-hooks.md

@@ -161,6 +161,55 @@ Note that you can also interpolate [arbitrary environment
 variables](https://torsion.org/borgmatic/reference/configuration/environment-variables/).
 
 
+## Soft failure
+
+If any of your hook commands return a special exit status of 75, that indicates
+to borgmatic that it's a temporary failure and borgmatic should skip all
+subsequent actions for the current repository.
+
+If you return any status besides 75, then it's a standard success or error.
+(Zero is success; anything else other than 75 is an error).
+
+Example of a soft failure command:
+
+```yaml
+commands:
+    - before: repository
+      run:
+          - findmnt /mnt/removable > /dev/null || exit 75
+```
+
+### Caveats and details
+
+There are some caveats you should be aware of with this feature.
+
+ * You'll generally want to put a soft failure command in a `before` command
+   hook, so as to gate whether the backup action occurs. While a soft failure is
+   also supported in an `after` command hook, returning a soft failure there
+   won't prevent any actions from occurring, because they've already occurred!
+   Similarly, you can return a soft failure from an `error` command hook, but at
+   that point it's too late to prevent the error.
+ * Returning a soft failure does prevent further commands in the same hook from
+   executing. So, like a standard error, it is an "early out." Unlike a standard
+   error, borgmatic does not display it in angry red text or consider it a
+   failure.
+ * <span class="minilink minilink-addedin">New in version 1.9.0</span> Soft
+   failures in `action` or `before_*` command hooks only skip the current
+   repository rather than all repositories in a configuration file.
+ * If you're writing a soft failure script that you want to vary based on the
+   current repository, for instance so you can have multiple repositories in a
+   single configuration file, have a look at [variable
+   interpolation](#variable-interpolation) above.
+   And there's always still the option of putting anything that you don't want
+   soft-failed (like always-online cloud backups) in separate configuration
+   files from your soft-failing repositories.
+ * The soft failure doesn't have to test anything related to a repository. You
+   can even perform a test that individual source directories are mounted and
+   available. Use your imagination!
+ * Soft failures are not currently implemented for `everything`,
+   `before_everything`, or `after_everything` command hooks.
+
+
 ## Full configuration
 
 ```yaml

docs/reference/source-code.md

@@ -26,3 +26,34 @@ started. Starting at the top level, we have:
 
 So, broadly speaking, the control flow goes: `commands` → `config` followed by
 `commands` → `actions` → `borg` and `hooks`.
+
+
+## Code style
+
+When writing code for borgmatic, start with [PEP
+8](https://www.python.org/dev/peps/pep-0008/). But then, apply the following
+deviations from it:
+
+ * For strings, prefer single quotes over double quotes.
+ * Limit all lines to a maximum of 100 characters.
+ * Use trailing commas within multiline values or argument lists.
+ * For multiline constructs, put opening and closing delimiters on lines
+   separate from their contents.
+ * Within multiline constructs, use standard four-space indentation. Don't align
+   indentation with an opening delimiter.
+ * In general, spell out words in variable names instead of shortening them.
+   So, think `index` instead of `idx`. There are some notable exceptions to
+   this though (like `config`).
+ * Favor blank lines around logical code groupings, `if` statements,
+   `return`s, etc. Readability is more important than packing code tightly.
+ * Import fully qualified Python modules instead of importing individual
+   functions, classes, or constants. E.g., do `import os.path` instead of
+   `from os import path`. (Some exceptions to this are made in tests.)
+ * Only use classes and OOP as a last resort, such as when integrating with
+   Python libraries that require it.
+ * Prefer functional code where it makes sense, e.g. when constructing a
+   command (to subsequently execute imperatively).
+
+Since borgmatic uses [Ruff](https://docs.astral.sh/ruff/) for code lining and
+formatting, many other code style requirements are also enforced when running
+automated tests.

docs/search.md

@@ -1,5 +1,5 @@
 ---
-title: Search documentation
+title: Search the documentation
 eleventyExcludeFromCollections: true
 ---
 <link href="/borgmatic/pagefind/pagefind-ui.css" rel="stylesheet">