runtime(doc): Document ft_recommended_style

related: #20036

Signed-off-by: Christian Brabandt <cb@256bit.org>

diff --git a/runtime/doc/tags b/runtime/doc/tags
index 714a9b7dbe062c3261f52164b7c1665ff439439e..b065ca1480fa9935905ee4f71cd0fa12473757d9 100644 (file)
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -7746,6 +7746,7 @@ ft_hare.txt       ft_hare.txt     /*ft_hare.txt*
 ft_mp.txt      ft_mp.txt       /*ft_mp.txt*
 ft_ps1.txt     ft_ps1.txt      /*ft_ps1.txt*
 ft_raku.txt    ft_raku.txt     /*ft_raku.txt*
+ft_recommended_style   usr_51.txt      /*ft_recommended_style*
 ft_rust.txt    ft_rust.txt     /*ft_rust.txt*
 ft_sql.txt     ft_sql.txt      /*ft_sql.txt*
 ftdetect       filetype.txt    /*ftdetect*

diff --git a/runtime/doc/usr_51.txt b/runtime/doc/usr_51.txt
index 15ca4f50030aa36e31a6e1849d4e5bbcf0ee099a..b1b630454d33963835c4969cd54e93372de3fdee 100644 (file)
--- a/runtime/doc/usr_51.txt
+++ b/runtime/doc/usr_51.txt
@@ -1,4 +1,4 @@
-*usr_51.txt*   For Vim version 9.2.  Last change: 2026 Feb 14
+*usr_51.txt*   For Vim version 9.2.  Last change: 2026 May 26
 
 
                     VIM USER MANUAL    by Bram Moolenaar
@@ -573,6 +573,39 @@ be set accordingly.
 
 Both these variables use legacy script syntax, not |Vim9| syntax.
 
+RECOMMENDED STYLE                              *ft_recommended_style*
+
+A filetype plugin or indent script may set options that reflect a
+recommended or commonly used style for that filetype, rather than a strict
+requirement of the language.  Since not every user wants these stylistic
+settings, guard them so they can be disabled.
+
+Check two variables, the filetype-specific one first, then the general one,
+defaulting to enabled (1): >
+
+       if get(g:, '<filetype>_recommended_style',
+               \ get(g:, 'filetype_recommended_style', 1))
+         " set the recommended style options here
+       endif
+
+Replace <filetype> with the actual filetype name, e.g. "python" gives
+g:python_recommended_style.
+
+This lets the user turn recommended style settings off for all filetypes: >
+
+       let g:filetype_recommended_style = 0
+
+or for one filetype while leaving the rest enabled: >
+
+       let g:python_recommended_style = 0
+
+The filetype-specific variable takes precedence over the general one, so a
+user can disable styling everywhere with g:filetype_recommended_style and
+re-enable it for a single filetype by setting g:<filetype>_recommended_style
+to 1 (or vice versa).
+
+Settings that are required for the language to work correctly (not merely
+stylistic) should not be placed behind this guard.
 
 FILE NAME