Merge pull request #17479 from dundargoc/docs/usr04/update-Y-description

docs: update explanation of Y to reflect new defaults

runtime/doc/index.txt

@@ -353,6 +353,7 @@ tag		char	      note action in Normal mode	~
 				   register x]
 |Y|		["x]Y		   yank N lines [into register x]; synonym for
 				   "yy"
+				   Note: Mapped to "y$" by default. |default-mappings|
 |ZZ|		ZZ		   write if buffer changed and close window
 |ZQ|		ZQ		   close window without writing
 |[|		[{char}		   square bracket command (see |[| below)

runtime/doc/quickref.txt

@@ -356,6 +356,7 @@ In Insert or Command-line mode:
 |v_y|	     {visual}y	yank the highlighted text into a register
 |yy|	  N  yy		yank N lines into a register
 |Y|	  N  Y		yank N lines into a register
+			Note: Mapped to "y$" by default. |default-mappings|
 |p|	  N  p		put a register after the cursor position (N times)
 |P|	  N  P		put a register before the cursor position (N times)
 |]p|	  N  ]p		like p, but adjust indent to current line

runtime/doc/usr_04.txt

@@ -349,15 +349,17 @@ Notice that "yw" includes the white space after a word.  If you don't want
 this, use "ye".
 
 The "yy" command yanks a whole line, just like "dd" deletes a whole line.
-Unexpectedly, while "D" deletes from the cursor to the end of the line, "Y"
-works like "yy", it yanks the whole line.  Watch out for this inconsistency!
-Use "y$" to yank to the end of the line.
 
 	a text line   yy	a text line	       a text line
 	line 2			line 2		p      line 2
 	last line		last line	       a text line
 						       last line
 
+"Y" was originally equivalent to "yank the entire line", as opposed to "D"
+which is "delete to end of the line".  "Y" has thus been remapped to mean
+"yank to end of the line" to make it consistent with the behavior of "D".
+Mappings will be covered in later chapters.
+
 ==============================================================================
 *04.7*	Using the clipboard
 

runtime/doc/usr_07.txt

@@ -336,7 +336,7 @@ there. >
 
 Of course you can use many other commands to yank the text.  For example, to
 select whole lines start Visual mode with "V".  Or use CTRL-V to select a
-rectangular block.  Or use "Y" to yank a single line, "yaw" to yank-a-word,
+rectangular block.  Or use "yy" to yank a single line, "yaw" to yank-a-word,
 etc.
    The "p" command puts the text after the cursor.  Use "P" to put the text
 before the cursor.  Notice that Vim remembers if you yanked a whole line or a
@@ -359,7 +359,7 @@ the text should be placed in the f register.  This must come just before the
 yank command.
    Now yank three whole lines to the l register (l for line): >
 
-	"l3Y
+	"l3yy
 
 The count could be before the "l just as well.  To yank a block of text to the
 b (for block) register: >

runtime/doc/usr_10.txt

@@ -132,11 +132,11 @@ This works both with recording and with yank and delete commands.  For
 example, you want to collect a sequence of lines into the a register.  Yank
 the first line with: >
 
-	"aY
+	"ayy
 
 Now move to the second line, and type: >
 
-	"AY
+	"Ayy
 
 Repeat this command for all lines.  The a register now contains all those
 lines, in the order you yanked them.