Could Someone Provide a Broken down Description for the Vim Command gqip?

Question

My understanding is that the command gqip, when in normal mode, tells vim to format the current paragraph, separated by whitespace, using the formatoptions as rules. But I can't find any information on the command itself to see other possible use-cases like it. More specifically, what I would like to know is if you break up the command gqip into g, q, i, and p, what do these individual components do to give the command its behaviour?

Answer 1

gq{motion} (:help gq) Formats the lines covered by {motion}.

A motion can generally be any command that would move the cursor, in which case it covers everything between the initial and final cursor positions, or a "text object".

:help text-objects lists all the text objects, specifically:

ip "inner paragraph", select [count] paragraphs (see |paragraph|). Exception: a blank line (only containing white space) is also a paragraph boundary. When used in Visual mode it is made linewise.

Answer 2

This question illustrates one of the biggest problems of relying on random, disconnected, pieces of information gathered from random sources instead of learning Vim properly.

gqip is really gq, an operator, and ip, a motion.

The concepts of "operator" and "motion" are introduced in lesson 2 of $ vimtutor and further discussed in chapter 4 of the user manual: :help 04.1, while the concept of text object is introduced a little further in the same chapter: :help 04.8.

Learning Vim is not even "like" learning a language, it is learning a language and the user manual is structured in a way that follows common language teaching techniques: in the beginning, the user is given a handful of basic commands ( "delete", "yank", "to next word", etc., a vocabulary) and shown how to compose them (a grammar) to affect the text in a file. The idea is to start simple and gradually introduce more vocabulary and more grammar rules.

Once the user has internalised some vocabulary and some grammar, they can acquire new commands easily and immediately compose them with previously acquired ones in more complex "sentences", just like a language learner.

And, FWIW, here is the whole :help 10.7, which happens to cover gqap, which is easy to extrapolate to any gq + motion, thanks to what you learned earlier, in chapter 4:

10.7 Formatting text

When you are typing plain text, it's nice if the length of each line is automatically trimmed to fit in the window. To make this happen while inserting text, set the 'textwidth' option:

:set textwidth=72

You might remember that in the example vimrc file this command was used for every text file. Thus if you are using that vimrc file, you were already using it. To check the current value of 'textwidth':

:set textwidth

Now lines will be broken to take only up to 72 characters. But when you insert text halfway through a line, or when you delete a few words, the lines will get too long or too short. Vim doesn't automatically reformat the text. To tell Vim to format the current paragraph:

gqap

This starts with the "gq" command, which is an operator. Following is "ap", the text object that stands for "a paragraph". A paragraph is separated from the next paragraph by an empty line.

Note: A blank line, which contains white space, does NOT separate paragraphs. This is hard to notice!

Instead of "ap" you could use any motion or text object. If your paragraphs are properly separated, you can use this command to format the whole file:

gggqG

"gg" takes you to the first line, "gq" is the format operator and "G" the motion that jumps to the last line.

In case your paragraphs aren't clearly defined, you can format just the lines you manually select. Move the cursor to the first line you want to format. Start with the command "gqj". This formats the current line and the one below it. If the first line was short, words from the next line will be appended. If it was too long, words will be moved to the next line. The cursor moves to the second line. Now you can use "." to repeat the command. Keep doing this until you are at the end of the text you want to format.

With the foundational knowledge provided by :help user-manual, gqip can't be a mystery.