runtime(doc): deduplicate getpos(), line(), col(), virtcol()

Move the main description to getpos() and link to that from the other
functions.

closes: #14970

Signed-off-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>

1 files changed, 55 insertions, 58 deletions

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 66f1bae132..8f2d132e29 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -1,4 +1,4 @@
-*builtin.txt*	For Vim version 9.1.  Last change: 2024 Jun 11
+*builtin.txt*	For Vim version 9.1.  Last change: 2024 Jun 12
 
 
 		  VIM REFERENCE MANUAL	  by Bram Moolenaar
@@ -1727,33 +1727,30 @@ clearmatches([{win}])					*clearmatches()*
 
 col({expr} [, {winid}])					*col()*
 		The result is a Number, which is the byte index of the column
-		position given with {expr}.  The accepted positions are:
-		    .	    the cursor position
-		    $	    the end of the cursor line (the result is the
-			    number of bytes in the cursor line plus one)
-		    'x	    position of mark x (if the mark is not set, 0 is
-			    returned)
-		    v       In Visual mode: the start of the Visual area (the
-			    cursor is the end).  When not in Visual mode
-			    returns the cursor position.  Differs from |'<| in
-			    that it's updated right away.
+		position given with {expr}.
+		For accepted positions see |getpos()|.
 		Additionally {expr} can be [lnum, col]: a |List| with the line
 		and column number. Most useful when the column is "$", to get
 		the last column of a specific line.  When "lnum" or "col" is
 		out of range then col() returns zero.
+
 		With the optional {winid} argument the values are obtained for
 		that window instead of the current window.
+
 		To get the line number use |line()|.  To get both use
 		|getpos()|.
 		For the screen column position use |virtcol()|.  For the
 		character position use |charcol()|.
+
 		Note that only marks in the current file can be used.
+
 		Examples: >
 			col(".")		column of cursor
 			col("$")		length of cursor line plus one
 			col("'t")		column of mark t
 			col("'" .. markname)	column of mark markname
-<		The first column is 1.  Returns 0 if {expr} is invalid or when
+<
+		The first column is 1.  Returns 0 if {expr} is invalid or when
 		the window with ID {winid} is not found.
 		For an uppercase mark the column may actually be in another
 		buffer.
@@ -4490,9 +4487,34 @@ getpid()							*getpid()*
 
 
 getpos({expr})							*getpos()*
-		Get the position for String {expr}.  For possible values of
-		{expr} see |line()|.  For getting the cursor position see
-		|getcurpos()|.
+		Get the position for String {expr}.
+		The accepted values for {expr} are:		*E1209*
+		    .	    The cursor position.
+		    $	    The last line in the current buffer.
+		    'x	    Position of mark x (if the mark is not set, 0 is
+			    returned).
+		    w0	    First line visible in current window (one if the
+			    display isn't updated, e.g. in silent Ex mode).
+		    w$	    Last line visible in current window (this is one
+			    less than "w0" if no lines are visible).
+		    v	    When not in Visual mode, returns the cursor
+			    position.  In Visual mode, returns the other end
+			    of the Visual area.  A good way to think about
+			    this is that in Visual mode "v" and "." complement
+			    each other.  While "." refers to the cursor
+			    position, "v" refers to where |v_o| would move the
+			    cursor.  As a result, you can use "v" and "."
+			    together to work on all of a selection in
+			    characterwise Visual mode.  If the cursor is at
+			    the end of a characterwise Visual area, "v" refers
+			    to the start of the same Visual area.  And if the
+			    cursor is at the start of a characterwise Visual
+			    area, "v" refers to the end of the same Visual
+			    area.  "v" differs from |'<| and |'>| in that it's
+			    updated right away.
+		Note that a mark in another file can be used.  The line number
+		then applies to another buffer.
+
 		The result is a |List| with four numbers:
 		    [bufnum, lnum, col, off]
 		"bufnum" is zero, unless a mark like '0 or 'A is used, then it
@@ -4503,19 +4525,24 @@ getpos({expr})							*getpos()*
 		it is the offset in screen columns from the start of the
 		character.  E.g., a position within a <Tab> or after the last
 		character.
-		Note that for '< and '> Visual mode matters: when it is "V"
-		(visual line mode) the column of '< is zero and the column of
-		'> is a large number equal to |v:maxcol|.
+
+		For getting the cursor position see |getcurpos()|.
 		The column number in the returned List is the byte position
 		within the line. To get the character position in the line,
 		use |getcharpos()|.
+
+		Note that for '< and '> Visual mode matters: when it is "V"
+		(visual line mode) the column of '< is zero and the column of
+		'> is a large number equal to |v:maxcol|.
 		A very large column number equal to |v:maxcol| can be returned,
 		in which case it means "after the end of the line".
 		If {expr} is invalid, returns a list with all zeros.
+
 		This can be used to save and restore the position of a mark: >
 			let save_a_mark = getpos("'a")
 			...
 			call setpos("'a", save_a_mark)
+
 <		Also see |getcharpos()|, |getcurpos()| and |setpos()|.
 
 		Can also be used as a |method|: >
@@ -6182,37 +6209,16 @@ libcallnr({libname}, {funcname}, {argument})
 line({expr} [, {winid}])				*line()*
 		The result is a Number, which is the line number of the file
 		position given with {expr}.  The {expr} argument is a string.
-		The accepted positions are:			 *E1209*
-		    .	    the cursor position
-		    $	    the last line in the current buffer
-		    'x	    position of mark x (if the mark is not set, 0 is
-			    returned)
-		    w0	    first line visible in current window (one if the
-			    display isn't updated, e.g. in silent Ex mode)
-		    w$	    last line visible in current window (this is one
-			    less than "w0" if no lines are visible)
-		    v	    When not in Visual mode, returns the cursor
-			    position.  In Visual mode, returns the other end
-			    of the Visual area.  A good way to think about
-			    this is that in Visual mode "v" and "." complement
-			    each other.  While "." refers to the cursor
-			    position, "v" refers to where |v_o| would move the
-			    cursor.  As a result, you can use "v" and "."
-			    together to work on all of a selection in
-			    characterwise visual mode.  If the cursor is at
-			    the end of a characterwise visual area, "v" refers
-			    to the start of the same visual area.  And if the
-			    cursor is at the start of a characterwise visual
-			    area, "v" refers to the end of the same visual
-			    area.  "v" differs from |'<| and |'>| in that it's
-			    updated right away.
-		Note that a mark in another file can be used.  The line number
-		then applies to another buffer.
+		See |getpos()| for accepted positions.
+
 		To get the column number use |col()|.  To get both use
 		|getpos()|.
+
 		With the optional {winid} argument the values are obtained for
 		that window instead of the current window.
+
 		Returns 0 for invalid values of {expr} and {winid}.
+
 		Examples: >
 			line(".")		line number of the cursor
 			line(".", winid)	idem, in window "winid"
@@ -11747,7 +11753,7 @@ virtcol({expr} [, {list} [, {winid}]])			*virtcol()*
 		set to 8, it returns 8. |conceal| is ignored.
 		For the byte position use |col()|.
 
-		For the use of {expr} see |col()|.
+		For the use of {expr} see |getpos()| and |col()|.
 
 		When 'virtualedit' is used {expr} can be [lnum, col, off],
 		where "off" is the offset in screen columns from the start of
@@ -11757,18 +11763,6 @@ virtcol({expr} [, {list} [, {winid}]])			*virtcol()*
 		beyond the end of the line can be returned.  Also see
 		|'virtualedit'|
 
-		The accepted positions are:
-		    .	    the cursor position
-		    $	    the end of the cursor line (the result is the
-			    number of displayed characters in the cursor line
-			    plus one)
-		    'x	    position of mark x (if the mark is not set, 0 is
-			    returned)
-		    v       In Visual mode: the start of the Visual area (the
-			    cursor is the end).  When not in Visual mode
-			    returns the cursor position.  Differs from |'<| in
-			    that it's updated right away.
-
 		If {list} is present and non-zero then virtcol() returns a
 		List with the first and last screen position occupied by the
 		character.
@@ -11777,6 +11771,7 @@ virtcol({expr} [, {list} [, {winid}]])			*virtcol()*
 		that window instead of the current window.
 
 		Note that only marks in the current file can be used.
+
 		Examples: >
 			" With text "foo^Lbar" and cursor on the "^L":
 
@@ -11787,7 +11782,9 @@ virtcol({expr} [, {list} [, {winid}]])			*virtcol()*
 			" With text "	  there", with 't at 'h':
 
 			virtcol("'t")	" returns 6
-<		The first column is 1.  0 or [0, 0] is returned for an error.
+<
+		The first column is 1.  0 or [0, 0] is returned for an error.
+
 		A more advanced example that echoes the maximum length of
 		all lines: >
 		    echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))