runtime(comment): include a simple comment toggling plugin

fixes #14626
closes: #14634

Signed-off-by: Maxim Kim <habamax@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

8 files changed, 147 insertions, 2 deletions

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 63d6735c59..d5ac02ef47 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -316,6 +316,7 @@ runtime/lang/menu_ru_ru.cp1251.vim	@RestorerZ
 runtime/lang/menu_ru_ru.koi8-r.vim	@RestorerZ
 runtime/lang/menu_ru_ru.utf-8.vim	@RestorerZ
 runtime/pack/dist/opt/cfilter/plugin/cfilter.vim	@yegappan
+runtime/pack/dist/opt/comment/	@habamax
 runtime/pack/dist/opt/matchit/		@chrisbra
 runtime/plugin/manpager.vim		@Konfekt
 runtime/syntax/shared/hgcommitDiff.vim	@vegerot
diff --git a/Filelist b/Filelist
index 57eb8dd402..ff474bc642 100644
--- a/Filelist
+++ b/Filelist
@@ -755,6 +755,10 @@ RT_ALL =	\
 		runtime/tutor/tutor.vim \
 		runtime/vimrc_example.vim \
 		runtime/pack/dist/opt/cfilter/plugin/cfilter.vim \
+		runtime/pack/dist/opt/comment/plugin/comment.vim \
+		runtime/pack/dist/opt/comment/doc/comment.txt \
+		runtime/pack/dist/opt/comment/doc/tags \
+		runtime/pack/dist/opt/comment/autoload/comment.vim \
 		runtime/pack/dist/opt/dvorak/plugin/dvorak.vim \
 		runtime/pack/dist/opt/dvorak/dvorak/enable.vim \
 		runtime/pack/dist/opt/dvorak/dvorak/disable.vim \
diff --git a/runtime/doc/tags b/runtime/doc/tags
index dcd8db7e2a..56a38dcbd2 100644
--- a/runtime/doc/tags
+++ b/runtime/doc/tags
@@ -6515,6 +6515,7 @@ command-block	vim9.txt	/*command-block*
 command-line-functions	usr_41.txt	/*command-line-functions*
 command-line-window	cmdline.txt	/*command-line-window*
 command-mode	intro.txt	/*command-mode*
+comment-install	usr_05.txt	/*comment-install*
 compatible-default	starting.txt	/*compatible-default*
 compile-changes-5	version5.txt	/*compile-changes-5*
 compile-changes-6	version6.txt	/*compile-changes-6*
diff --git a/runtime/doc/usr_05.txt b/runtime/doc/usr_05.txt
index 05239eeeb6..063af9bfc7 100644
--- a/runtime/doc/usr_05.txt
+++ b/runtime/doc/usr_05.txt
@@ -1,4 +1,4 @@
-*usr_05.txt*	For Vim version 9.1.  Last change: 2023 Sep 12
+*usr_05.txt*	For Vim version 9.1.  Last change: 2024 Apr 26
 
 		     VIM USER MANUAL - by Bram Moolenaar
 
@@ -436,6 +436,18 @@ when Vim starts, add the following line to your vimrc file: >
 After restarting your Vim, the plugin is active and you can read about it at: >
 	:h editorconfig.txt
 
+
+Adding comment package					*comment-install*
+
+Load the plugin with this command: >
+    packadd comment
+<
+This way you can use the plugin with the default key bindings `gc` and similar
+for commenting (which is a well-established mapping in the Vim community).
+
+After restarting your Vim, the plugin is active and you can read about it at: >
+	:h comment.txt
+
 More information about packages can be found here: |packages|.
 
 ==============================================================================
diff --git a/runtime/doc/version9.txt b/runtime/doc/version9.txt
index c2779236ce..03050ee4db 100644
--- a/runtime/doc/version9.txt
+++ b/runtime/doc/version9.txt
@@ -1,4 +1,4 @@
-*version9.txt*  For Vim version 9.1.  Last change: 2024 Apr 14
+*version9.txt*  For Vim version 9.1.  Last change: 2024 Apr 26
 
 
 		  VIM REFERENCE MANUAL    by Bram Moolenaar
@@ -41554,6 +41554,7 @@ Enum support for Vim9 script |:enum|
 
 Other improvements				*new-other-9.2*
 ------------------
+The comment plugin |comment-install| is included.
 
 Changed						*changed-9.2*
 -------
diff --git a/runtime/pack/dist/opt/comment/autoload/comment.vim b/runtime/pack/dist/opt/comment/autoload/comment.vim
new file mode 100644
index 0000000000..9dda266ffa
--- /dev/null
+++ b/runtime/pack/dist/opt/comment/autoload/comment.vim
@@ -0,0 +1,58 @@
+vim9script
+
+# Maintainer: Maxim Kim <habamax@gmail.com>
+# Last Update: 2024-04-26
+#
+# Toggle comments
+# Usage:
+#   Add following mappings to vimrc:
+#       import autoload 'dist/comment.vim'
+#       nnoremap <silent> <expr> gc comment.Toggle()
+#       xnoremap <silent> <expr> gc comment.Toggle()
+#       nnoremap <silent> <expr> gcc comment.Toggle() .. '_'
+export def Toggle(...args: list<string>): string
+    if len(args) == 0
+        &opfunc = matchstr(expand('<stack>'), '[^. ]*\ze[')
+        return 'g@'
+    endif
+    if empty(&cms) || !&ma | return '' | endif
+    var cms = substitute(substitute(&cms, '\S\zs%s\s*', ' %s', ''), '%s\ze\S', '%s ', '')
+    var [lnum1, lnum2] = [line("'["), line("']")]
+    var cms_l = split(escape(cms, '*.'), '\s*%s\s*')
+    if len(cms_l) == 0 | return '' | endif
+    if len(cms_l) == 1 | call add(cms_l, '') | endif
+    var comment = 0
+    var indent_min = indent(lnum1)
+    var indent_start = matchstr(getline(lnum1), '^\s*')
+    for lnum in range(lnum1, lnum2)
+        if getline(lnum) =~ '^\s*$' | continue | endif
+        if indent_min > indent(lnum)
+            indent_min = indent(lnum)
+            indent_start = matchstr(getline(lnum), '^\s*')
+        endif
+        if getline(lnum) !~ $'^\s*{cms_l[0]}.*{cms_l[1]}$'
+            comment = 1
+        endif
+    endfor
+    var lines = []
+    var line = ''
+    for lnum in range(lnum1, lnum2)
+        if getline(lnum) =~ '^\s*$'
+            line = getline(lnum)
+        elseif comment
+            if exists("g:comment_first_col") || exists("b:comment_first_col")
+                # handle % with substitute
+                line = printf(substitute(cms, '%s\@!', '%%', 'g'), getline(lnum))
+            else
+                # handle % with substitute
+                line = printf(indent_start .. substitute(cms, '%s\@!', '%%', 'g'),
+                        strpart(getline(lnum), strlen(indent_start)))
+            endif
+        else
+            line = substitute(getline(lnum), $'^\s*\zs{cms_l[0]} \?\| \?{cms_l[1]}$', '', 'g')
+        endif
+        add(lines, line)
+    endfor
+    noautocmd keepjumps setline(lnum1, lines)
+    return ''
+enddef
diff --git a/runtime/pack/dist/opt/comment/doc/comment.txt b/runtime/pack/dist/opt/comment/doc/comment.txt
new file mode 100644
index 0000000000..e2bf7557fc
--- /dev/null
+++ b/runtime/pack/dist/opt/comment/doc/comment.txt
@@ -0,0 +1,59 @@
+*comment.txt*   For Vim version 9.1.  Last change:  2024 Apr 26
+
+
+		  VIM REFERENCE MANUAL
+
+Commenting and un-commenting text.
+
+==============================================================================
+
+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:
+
+							*gcc*
+gcc		to comment/uncomment current line
+							*o_gc*
+gc{motion}	to toggle comments for the selected motion
+							*gcip*
+gcip		to comment/uncomment current paragraph
+							*gcG*
+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
+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.
+
+You can simply configure this using the following autocommand (e.g. for legacy
+Vim script): >
+
+	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: >
+
+	autocmd Filetype vim :setlocal commentstring=#\ %s
+
+==============================================================================
+Options:
+
+*g:comment_first_col*
+*b:comment_first_col*
+    By default comment chars are added in front of the line, i.e. if the line
+    was indented, commented line would stay indented as well.
+
+    However some filetypes require a comment char on the first column, use this option
+    to change default behaviour.
+
+    Use g:comment_first_col to change it globally or b:comment_first_col to
+    target specific filetype(s).
+
+==============================================================================
+vim:tw=78:ts=8:fo=tcq2:ft=help:
diff --git a/runtime/pack/dist/opt/comment/plugin/comment.vim b/runtime/pack/dist/opt/comment/plugin/comment.vim
new file mode 100644
index 0000000000..94ac0670bf
--- /dev/null
+++ b/runtime/pack/dist/opt/comment/plugin/comment.vim
@@ -0,0 +1,9 @@
+vim9script
+
+# Maintainer: Maxim Kim <habamax@gmail.com>
+# Last Update: 2024-04-26
+
+import autoload 'comment.vim'
+nnoremap <silent> <expr> gc comment.Toggle()
+xnoremap <silent> <expr> gc comment.Toggle()
+nnoremap <silent> <expr> gcc comment.Toggle() .. '_'