Clarify constants/placeholders interaction and improve examples (#763).

borgmatic/config/schema.yaml

@@ -6,14 +6,15 @@ properties:
     constants:
         type: object
         description: |
-            Constants to use in the configuration file. All occurrences of the
+            Constants to use in the configuration file. Within option values,
-            constant name within curly braces will be replaced with the value.
+            all occurrences of the constant name in curly braces will be
-            For example, if you have a constant named "hostname" with the value
+            replaced with the constant value. For example, if you have a
-            "myhostname", then the string "{hostname}" will be replaced with
+            constant named "app_name" with the value "myapp", then the string
-            "myhostname" in the configuration file.
+            "{app_name}" will be replaced with "myapp" in the configuration
+            file.
         example:
-            hostname: myhostname
+            app_name: myapp
-            prefix: myprefix
+            user: myuser
     source_directories:
         type: array
         items:

docs/how-to/make-per-application-backups.md

@@ -301,7 +301,7 @@ options via an include and then overrides one of them locally:
 <<: !include /etc/borgmatic/common.yaml
 
 constants:
-    hostname: myhostname
+    base_directory: /opt
 
 repositories:
     - path: repo.borg
@@ -311,13 +311,13 @@ This is what `common.yaml` might look like:
 
 ```yaml
 constants:
-    prefix: myprefix
+    app_name: myapp
-    hostname: otherhost
+    base_directory: /var/lib
 ```
 
-Once this include gets merged in, the resulting configuration would have a
+Once this include gets merged in, the resulting configuration would have an
-`prefix` value of `myprefix` and an overridden `hostname` value of
+`app_name` value of `myapp` and an overridden `base_directory` value of
-`myhostname`.
+`/opt`.
 
 When there's an option collision between the local file and the merged
 include, the local file's option takes precedence.
@@ -540,7 +540,7 @@ tool is borgmatic's support for defining custom constants. This is similar to
 the [variable interpolation
 feature](https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/#variable-interpolation)
 for command hooks, but the constants feature lets you substitute your own
-custom values into anywhere in the entire configuration file.
+custom values into any option values in the entire configuration file.
 
 Here's an example usage:
 
@@ -563,10 +563,15 @@ forget to specify the section (like `location:` or `storage:`) that any option
 is in.
 
 In this example, when borgmatic runs, all instances of `{user}` get replaced
-with `foo` and all instances of `{archive_prefix}` get replaced with `bar-`.
+with `foo` and all instances of `{archive_prefix}` get replaced with `bar`.
-(And in this particular example, `{now}` doesn't get replaced with anything,
+And `{now}` doesn't get replaced with anything, but gets passed directly to
-but gets passed directly to Borg.) After substitution, the logical result
+Borg, which has its own
-looks something like this:
+[placeholders](https://borgbackup.readthedocs.io/en/stable/usage/help.html#borg-help-placeholders)
+using the same syntax as borgmatic constants. So borgmatic options like
+`archive_name_format` that get passed directly to Borg can use either Borg
+placeholders or borgmatic constants or both!
+
+After substitution, the logical result looks something like this:
 
 ```yaml
 source_directories: