runtime(comment): clarify the usage of 'commentstring' option value
Commit:
https://github.com/vim/vim/commit/98fb81846dd1da03c160bfa30dbf96ba48061d53
Author: Christian Brabandt <c...@256bit.org>
Date: Tue Jun 4 20:44:29 2024 +0200
runtime(comment): clarify the usage of 'commentstring' option value
fixes: https://github.com/vim/vim/issues/14905
Signed-off-by: Christian Brabandt <c...@256bit.org>
diff --git a/runtime/pack/dist/opt/comment/doc/comment.txt
b/runtime/pack/dist/opt/comment/doc/comment.txt
index e2bf7557f..25bd06756 100644
--- a/runtime/pack/dist/opt/comment/doc/comment.txt
+++ b/runtime/pack/dist/opt/comment/doc/comment.txt
@@ -1,4 +1,4 @@
-*comment.txt* For Vim version 9.1. Last change: 2024 Apr 26
+*comment.txt* For Vim version 9.1. Last change: 2024 Jun 04
VIM REFERENCE MANUAL
@@ -7,6 +7,8 @@ Commenting and un-commenting text.
==============================================================================
+See |comment-install| on how to activate this package.
+
The comment.vim package, allows to toggle comments for a single line, a range
of lines or a selected text object. It defines the following mappings:
@@ -21,20 +23,25 @@ gcG to comment/uncomment from current line till the
end of a buffer
*v_gc*
{Visual}gc to comment/uncomment the highlighted lines.
-The plugin uses the buffer-local 'commentstring' option value to add or remove
+This plugin uses the buffer-local 'commentstring' option value to add or remove
comment markers to the selected lines. Whether it will comment or un-comment
depends on the first line of the range of lines to act upon. When it matches
a comment marker, the line will be un-commented, if it doesn't, the line will
-be commented out. Blank and empty lines are not touched.
-
-If the mapping does not seem to work, chances are high, that this particular
-filetype is either not detected by Vim or the filetype plugin does not set the
-'commentstring' option.
+be commented out. Blank and empty lines are ignored.
+
+The comment marker will always be padded with blanks whether or not the
+'commentstring' value contains whitespace around "%s".
+
+If the mapping does not seem to work (or uses wrong comment markers), it might
+be because of several reasons:
+- the filetype is not detected by Vim, see |new-filetype|,
+- filetype plugins are not enabled, see |:filetype-plugin-on| or
+- the filetype plugin does not set the (correct) 'commentstring' option.
You can simply configure this using the following autocommand (e.g. for legacy
Vim script): >
- autocmd Filetype vim :setlocal commentstring="\ %s
+ autocmd Filetype vim :setlocal commentstring="%s
This example sets the " as start of a comment for legacy Vim Script. For Vim9
script, you would instead use the "#" char: >
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/vim_dev/E1sEZO9-00AEI6-II%40256bit.org.
