learnvimscriptthehardway

When using Vimscript, I'd avoid :normal-mode operations in favour of builtin functions that do the same things:

The backslashes inside the double quotes just need to be escaped once, so that "\\(" gives '\". The | however needs to be escaped twice, once for the double quotes, and once again because otherwise it would conclude the :map command. For that reason, I strongly recommend to use instead of \| inside of mappings. This is documented under :help map-bar.

Using a function as Kent suggested is cleaner and more maintainable, but I was able to modify the original mapping and will post it here for completeness.

igemnace gave me some pointers on the #vim IRC chat. The crucial piece is that I can search for a line-ending in the file (not a literal newline) by including \n in the search. Next, I need to change the motion characters since the match starts one line earlier. We need to go down a line from the upper match (j), and we don't need to go up (k) from the lower match. Finally, the search match region needs to be modified with \zs so if the cursor is on the line before the header, vim doesn't think the cursor is overlapping the match. That would cause the editor to delete the wrong section in that case. The logic is:

• search backwards for .*\zs\n--- \|\%$
• go down a line
• visual select until the next LOWER match

After all the escaping, that becomes:

Using instead of does what you are asking.

This command definition expands any supplied arguments when invoked

I am considering the first attempt in this working little improvement: