settings: Document <<MARKER heredoc syntax for multi-line values

Added in 2.4.5. Covers the new syntax.md section, updates the File
type description to prefer heredoc over inline: for config-file use,
and registers the settings_syntax_heredoc_added tag.

Author: cmouse

data/updates.js

@@ -172,6 +172,7 @@ export const updates = {
 	settings_passdb_mechanisms_filter_added: '2.4.0',
 	settings_passdb_static_password_added: '2.4.0',
 	settings_service_reuse_port_added: '2.4.4',
+	settings_syntax_heredoc_added: '2.4.5',
 	settings_ssl_client_ca_added: '2.4.0',
 	settings_ssl_imapc_removed: '2.4.0',
 	settings_ssl_request_client_cert_changed: '2.4.0',

docs/core/settings/syntax.md

@@ -449,6 +449,39 @@ read immediately whenever parsing the configuration file, so if it changes
 afterwards it requires a configuration reload to see the changes. This
 functionality is especially useful for reading SSL certificates and keys.
 
+## Inline Multi-line Values (Heredoc)
+
+[[added,settings_syntax_heredoc_added]]
+
+It's possible to set multi-line values directly in the configuration file
+using the heredoc syntax `<<MARKER`:
+
+```doveconf[dovecot.conf]
+key = <<END
+line one
+line two
+END
+```
+
+The marker (`END` above) can be any string that does not appear as a line on
+its own within the value. The terminating marker line must match exactly —
+any extra whitespace after the marker will prevent it from being recognized.
+Each content line is included in the value as-is, including a trailing newline.
+
+This is especially useful for [[link,settings_types_file,file settings]] such
+as SSL certificates and keys, where the content spans multiple lines:
+
+```doveconf[dovecot.conf]
+ssl_server_ca_file = <<END
+-----BEGIN CERTIFICATE-----
+...
+-----END CERTIFICATE-----
+END
+```
+
+`doveconf` output preserves the original marker, so `<<FOO` in `dovecot.conf`
+is reproduced as `<<FOO` in `doveconf` output.
+
 ## Variable Expansion
 
 It's possible to refer to other settings as `$SET:name`.

docs/core/settings/types.md

@@ -184,10 +184,19 @@ is delayed until the process accessing the setting expands it. The process
 is usually not running as root at this point, so you may need to adjust file
 permissions.
 
-It's possible to give inline values (instead of a path to a file) for the
-setting by using `inline:` prefix in the value. For example userdb could be
-returning `crypt_global_public_key_file=inline:<public key content>` without
-having to use files.
+It's possible to give inline values (instead of a path to a file) using the
+[[link,settings_syntax,heredoc syntax]] (`<<MARKER`). For example:
+
+```doveconf[dovecot.conf]
+ssl_server_ca_file = <<END
+-----BEGIN CERTIFICATE-----
+...
+-----END CERTIFICATE-----
+END
+```
+
+When returning file settings from userdb (where heredoc isn't available), use
+the `inline:` prefix: `crypt_global_public_key_file=inline:<public key content>`.
 
 ## Named Filter