[Backport release-0.8] docs(api): pattern is not expanded for autocommands (#20838)

docs(api): pattern is not expanded for autocommands

Problem: Unlike `:autocmd`, `nvim_create_autocommand()` does not expand
environment variables in the `pattern`, which is unexpected.

Solution: Add a note to the documentation explaining this and suggesting
using `expand()` explicitly.

(cherry picked from commit eeaf943ca3)

Co-authored-by: Christian Clason <c.clason@uni-graz.at>

runtime/doc/api.txt

@@ -3265,6 +3265,12 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
       pattern = { "*.py", "*.pyi" }
 <
 
+    Note: The `pattern` is passed to callbacks and commands as a literal string; environment
+    variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead,
+    |expand()| such variables explicitly: >
+      pattern = vim.fn.expand("~") .. "/some/path/*.py"
+<
+
     Example values for event: >
       "BufWritePre"
       {"CursorHold", "BufWritePre", "BufWritePost"}
@@ -3277,7 +3283,7 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                  • group (string|integer) optional: the autocommand group name
                    or id to match against.
                  • pattern (string|array) optional: pattern or patterns to
-                   match against |autocmd-pattern|.
+                   match literally against |autocmd-pattern|.
                  • buffer (integer) optional: buffer number for buffer local
                    autocommands |autocmd-buflocal|. Cannot be used with
                    {pattern}.

src/nvim/api/autocmd.c

@@ -401,6 +401,13 @@ cleanup:
 ///   pattern = { "*.py", "*.pyi" }
 /// </pre>
 ///
+/// Note: The `pattern` is passed to callbacks and commands as a literal string; environment
+/// variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|.
+/// Instead, |expand()| such variables explicitly:
+/// <pre>
+///   pattern = vim.fn.expand("~") .. "/some/path/*.py"
+/// </pre>
+///
 /// Example values for event:
 /// <pre>
 ///   "BufWritePre"
@@ -411,7 +418,7 @@ cleanup:
 /// @param opts Dictionary of autocommand options:
 ///             - group (string|integer) optional: the autocommand group name or
 ///             id to match against.
-///             - pattern (string|array) optional: pattern or patterns to match
+///             - pattern (string|array) optional: pattern or patterns to match literally
 ///             against |autocmd-pattern|.
 ///             - buffer (integer) optional: buffer number for buffer local autocommands
 ///             |autocmd-buflocal|. Cannot be used with {pattern}.