In vim, the macros are just stored in registers. You can recall the content of any register and execute it as a macro (which is what the @ does). To see a list of what is in your registers, use :reg.

You can see the contents of all the registers using the

:reg

command. Or an argument string like this

:reg ahx

will show you the contents of registers a, h, and x.

That way you can at least see what sequence of commands will be run and hopefully that will be clear enough for you to tell one from another.

The registers simply contain text. You can paste the command sequence in as text or you can copy text into a register and then run it as a command, depending on how you access the register.

I have not found any direct way to edit the contents of a register, but you can paste it into the file, edit it, and then save it back to the same register.

IHTH.

As /u/jheddings wrote the macros are stored as registers and what counts is the assignment of the code to the register (usually done in the vimrc files with let @a=blahblah To ease the way to display the macros you defined in your vimrc file (in my case it is in the ~/.vimrc path) you can use this vim function:

function! ShowMacros()
    10new
    exe  r!  .  grep -B 1 -E "^s*let @" ~/.vimrc 
    call cursor(1,1)
endfunction

What it does:

10new - open a new vim window with ten lines size

exe ... - execute a command and put in the window

call ... - go to the first line first column

You can execute this function by tipping in the normal mode :call ShowMacros

You could additionally create a key mapping or a command to fasten the way to call the function:

:cnoremap sm call ShowMacros()<CR>
command!  sm call ShowMacros()`

This is the original post where I wrote the function similar to the above.

The OP asked, "is there a way to attach some sort of documentation that would display with the macro to explain what it is for?"

I have found VI / VIM macros extremely obtuse to understand even a week after I ve written them, so I heartily support the idea of documentation. I have a suggestion for that, in two parts.

First is the process of documenting the macro in your .vimrc. I ve developed the following .vimrc comment format that helps me understand, a week or a year or more later, what a macro is supposed to be doing. E.g.:

"
"= GENERIC CLIPBOARD YANK  <F2>y (Y for Yank)
"= Yank the entire contents of the file into the clipboard; quit without saving.
"
"define F2 followed by y to be:
"|      Go to line 1.
"|      | From there, into the * buffer (system clipboard),
"|      | | yank to the end of the file.
"|      | | | Go to sleep for 1 second (to allow the clipboard to be updated).
"|      | | | |  Quit without saving the file.
"|      | | | |  |
map #2y 1G"*yG1gs:q!<CR>
"-------"-"-"-"--"------

Second, I am imagining that Jakub s ShowMacros() function above could be modified to grep a specific set of Help lines for each macro that would be in the file along with the definition, much the way the above command-line breakdown is attached to the definition, that would provide the needed User Help.

I ve flagged two lines above with "= at the beginning of each, so that they can become the User Help. Then Jakub s grep command would search for "^"= ". Here s the command I used. I m not sure if the -E for Extended Regular Expressions is needed and the -B 1 is a nice touch to include one line previous to a matching sequence, so here I have an explicitly empty comment line.

In my vimrc, I only needed one backslash, for the initial parsing of the definitions. Here s the line, replacing the one in Jakub s function definition above:

    exe  r!  .  grep -B 1 -E "^"= " ~/.vimrc  

Thanks to Jakub s hint, I now can generate help from my .vimrc in pretty much exactly the way the OP is asking for. I ve been using vi since 1983, so I m pretty stoked.

Thanks Jakub!

IHTH,

August