docs(vimdoc): Auto-generate user / API documentation + vimtags

Author: github-actions[bot]

doc/cursor-text-objects.txt

@@ -1,4 +1,4 @@
-*cursor-text-objects.txt*   For Neovim >= 0.8.0  Last change: 2024 November 23
+*cursor-text-objects.txt*   For Neovim >= 0.8.0  Last change: 2024 November 25
 
 ==============================================================================
 Table of Contents                      *cursor-text-objects-table-of-contents*
@@ -8,11 +8,12 @@ Table of Contents                      *cursor-text-objects-table-of-contents*
   - Summary                           |cursor-text-objects-how-to-use-summary|
   - Details                           |cursor-text-objects-how-to-use-details|
 3. Installation                             |cursor-text-objects-installation|
-4. Tests                                           |cursor-text-objects-tests|
+4. Disclaimer                                 |cursor-text-objects-disclaimer|
+5. Tests                                           |cursor-text-objects-tests|
   - Initialization                  |cursor-text-objects-tests-initialization|
   - Running                                |cursor-text-objects-tests-running|
-5. Tracking Updates                     |cursor-text-objects-tracking-updates|
-6. Other Plugins                           |cursor-text-objects-other-plugins|
+6. Tracking Updates                     |cursor-text-objects-tracking-updates|
+7. Other Plugins                           |cursor-text-objects-other-plugins|
 
 ==============================================================================
 1. cursor-text-objects.nvim     *cursor-text-objects-cursor-text-objects.nvim*
@@ -127,7 +128,40 @@ Give your right-pinky a workout and install `cursor-text-objects.nvim` today!
 
 
 ==============================================================================
-4. Tests                                           *cursor-text-objects-tests*
+4. Disclaimer                                 *cursor-text-objects-disclaimer*
+
+The default recommended mappings, `[` and `]`, will not conflict with existing
+mappings. There’s a test script
+<https://gist.github.com/ColinKennedy/7e632f88570be89762b0ca8372769b72> that
+verifies this.
+
+However if you have another mapping like this:
+
+`vim.keymap.set({'n', 'x', 'o'}, '[i', function() return "dd" end,
+{expr=true})`
+
+then you may be surprised that `d[ip` does not work.
+
+In short while actually this is not a conflict, it can still be confusing for a
+you and you’ll want to remap `cursor-text-objects` or that other mapping /
+plug-in to avoid the issue.
+
+More details on what is going on in this case ~
+
+`cursor-text-objects` is a pending operator but the mapping above is a regular
+operator. A pending operator is a mapping that "waits for the user to keep
+typing more keys" but a regular operator executes immediately. So if you only
+have `cursor-text-objects` applied, `ip` is interpreted as "[i]nside
+[p]aragraph". But with the mapping above, `d[i` executes immediately and then
+treats `p` as the start of a new command. And `p` as a standalone keymap means
+[p]ut. (See `:help put` for details).
+
+So again this is all expected behavior but if you don’t want that to happen,
+you’re better off remapping `[i` to something else.
+
+
+==============================================================================
+5. Tests                                           *cursor-text-objects-tests*
 
 
 INITIALIZATION                      *cursor-text-objects-tests-initialization*
@@ -159,7 +193,7 @@ Run test based on tags
 
 
 ==============================================================================
-5. Tracking Updates                     *cursor-text-objects-tracking-updates*
+6. Tracking Updates                     *cursor-text-objects-tracking-updates*
 
 See doc/news.txt <doc/news.txt> for updates.
 
@@ -171,7 +205,7 @@ You can watch this plugin for changes by adding this URL to your RSS feed:
 
 
 ==============================================================================
-6. Other Plugins                           *cursor-text-objects-other-plugins*
+7. Other Plugins                           *cursor-text-objects-other-plugins*
 
 This plugin is a sort-of successor to vim-ninja-feet
 <https://github.com/tommcdo/vim-ninja-feet> with some notable differences

doc/tags

@@ -1,4 +1,5 @@
 cursor-text-objects-cursor-text-objects.nvim	cursor-text-objects.txt	/*cursor-text-objects-cursor-text-objects.nvim*
+cursor-text-objects-disclaimer	cursor-text-objects.txt	/*cursor-text-objects-disclaimer*
 cursor-text-objects-how-to-use	cursor-text-objects.txt	/*cursor-text-objects-how-to-use*
 cursor-text-objects-how-to-use-details	cursor-text-objects.txt	/*cursor-text-objects-how-to-use-details*
 cursor-text-objects-how-to-use-summary	cursor-text-objects.txt	/*cursor-text-objects-how-to-use-summary*