From 3344b8c71c8945c36fc6868a723c0c65c7e43498 Mon Sep 17 00:00:00 2001
From: Aki Tuomi <aki.tuomi@open-xchange.com>
Date: Sat, 2 May 2026 18:13:09 +0300
Subject: [PATCH] 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.
---
 data/updates.js              |  1 +
 docs/core/settings/syntax.md | 33 +++++++++++++++++++++++++++++++++
 docs/core/settings/types.md  | 17 +++++++++++++----
 3 files changed, 47 insertions(+), 4 deletions(-)

diff --git a/data/updates.js b/data/updates.js
index a473becc2..8f427436d 100644
--- a/data/updates.js
+++ b/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',
diff --git a/docs/core/settings/syntax.md b/docs/core/settings/syntax.md
index 834ce055d..722454c36 100644
--- a/docs/core/settings/syntax.md
+++ b/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`.
diff --git a/docs/core/settings/types.md b/docs/core/settings/types.md
index 5edf46881..33a3c015c 100644
--- a/docs/core/settings/types.md
+++ b/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