FM / doc

/usr/share/vim/vim82/doc

Name	Size	Mode	Actions
arabic.txt	11901	0644	edit dl rm
autocmd.txt	72220	0644	edit dl rm
change.txt	78049	0644	edit dl rm
channel.txt	50309	0644	edit dl rm
cmdline.txt	49342	0644	edit dl rm
debug.txt	6896	0644	edit dl rm
debugger.txt	5443	0644	edit dl rm
develop.txt	22861	0644	edit dl rm
diff.txt	17024	0644	edit dl rm
digraph.txt	61978	0644	edit dl rm
editing.txt	74161	0644	edit dl rm
eval.txt	541209	0644	edit dl rm
farsi.txt	523	0644	edit dl rm
filetype.txt	27594	0644	edit dl rm
fold.txt	23689	0644	edit dl rm
ft_ada.txt	18246	0644	edit dl rm
ft_rust.txt	9596	0644	edit dl rm
ft_sql.txt	30700	0644	edit dl rm
gui.txt	52741	0644	edit dl rm
gui_w32.txt	19451	0644	edit dl rm
gui_x11.txt	29906	0644	edit dl rm
hangulin.txt	598	0644	edit dl rm
hebrew.txt	5666	0644	edit dl rm
help.txt	8899	0644	edit dl rm
helphelp.txt	15729	0644	edit dl rm
howto.txt	2916	0644	edit dl rm
if_cscop.txt	19325	0644	edit dl rm
if_lua.txt	16755	0644	edit dl rm
if_mzsch.txt	11941	0644	edit dl rm
if_ole.txt	7361	0644	edit dl rm
if_perl.txt	11281	0644	edit dl rm
if_pyth.txt	38435	0644	edit dl rm
if_ruby.txt	8516	0644	edit dl rm
if_sniff.txt	271	0644	edit dl rm
if_tcl.txt	22951	0644	edit dl rm
indent.txt	42284	0644	edit dl rm
index.txt	80638	0644	edit dl rm
insert.txt	85294	0644	edit dl rm
intro.txt	38972	0644	edit dl rm
map.txt	70799	0644	edit dl rm
mbyte.txt	59642	0644	edit dl rm
message.txt	31425	0644	edit dl rm
mlang.txt	8187	0644	edit dl rm
motion.txt	51341	0644	edit dl rm
netbeans.txt	37982	0644	edit dl rm
options.txt	391308	0644	edit dl rm
os_390.txt	4749	0644	edit dl rm
os_amiga.txt	5466	0644	edit dl rm
os_beos.txt	293	0644	edit dl rm
os_dos.txt	12378	0644	edit dl rm
os_haiku.txt	8592	0644	edit dl rm
os_mac.txt	6856	0644	edit dl rm
os_mint.txt	391	0644	edit dl rm
os_msdos.txt	523	0644	edit dl rm
os_os2.txt	299	0644	edit dl rm
os_qnx.txt	4071	0644	edit dl rm
os_risc.txt	328	0644	edit dl rm
os_unix.txt	2603	0644	edit dl rm
os_vms.txt	32906	0644	edit dl rm
os_win32.txt	13351	0644	edit dl rm
pattern.txt	60137	0644	edit dl rm
pi_getscript.txt	21082	0644	edit dl rm
pi_gzip.txt	1294	0644	edit dl rm
pi_logipat.txt	4196	0644	edit dl rm
pi_netrw.txt	179286	0644	edit dl rm
pi_paren.txt	2274	0644	edit dl rm
pi_spec.txt	4127	0644	edit dl rm
pi_tar.txt	6813	0644	edit dl rm
pi_vimball.txt	11859	0644	edit dl rm
pi_zip.txt	7294	0644	edit dl rm
popup.txt	39472	0644	edit dl rm
print.txt	31025	0644	edit dl rm
quickfix.txt	82925	0644	edit dl rm
quickref.txt	72144	0644	edit dl rm
quotes.txt	12748	0644	edit dl rm
recover.txt	10720	0644	edit dl rm
remote.txt	8417	0644	edit dl rm
repeat.txt	42186	0644	edit dl rm
rileft.txt	4938	0644	edit dl rm
russian.txt	3024	0644	edit dl rm
scroll.txt	13781	0644	edit dl rm
sign.txt	25859	0644	edit dl rm
spell.txt	64099	0644	edit dl rm
sponsor.txt	7203	0644	edit dl rm
starting.txt	73591	0644	edit dl rm
syntax.txt	225863	0644	edit dl rm
tabpage.txt	17248	0644	edit dl rm
tags	354812	0644	edit dl rm
tagsrch.txt	40278	0644	edit dl rm
term.txt	47498	0644	edit dl rm
terminal.txt	56100	0644	edit dl rm
testing.txt	14954	0644	edit dl rm
textprop.txt	13402	0644	edit dl rm
tips.txt	21067	0644	edit dl rm
todo.txt	309420	0644	edit dl rm
uganda.txt	14028	0644	edit dl rm
undo.txt	16584	0644	edit dl rm
usr_01.txt	7081	0644	edit dl rm
usr_02.txt	24226	0644	edit dl rm
usr_03.txt	23872	0644	edit dl rm
usr_04.txt	19131	0644	edit dl rm
usr_05.txt	27023	0644	edit dl rm
usr_06.txt	9611	0644	edit dl rm
usr_07.txt	15995	0644	edit dl rm
usr_08.txt	19378	0644	edit dl rm
usr_09.txt	11502	0644	edit dl rm
usr_10.txt	29200	0644	edit dl rm
usr_11.txt	13025	0644	edit dl rm
usr_12.txt	13429	0644	edit dl rm
usr_20.txt	13709	0644	edit dl rm
usr_21.txt	18456	0644	edit dl rm
usr_22.txt	14999	0644	edit dl rm
usr_23.txt	12744	0644	edit dl rm
usr_24.txt	20827	0644	edit dl rm
usr_25.txt	19176	0644	edit dl rm
usr_26.txt	8259	0644	edit dl rm
usr_27.txt	17709	0644	edit dl rm
usr_28.txt	16020	0644	edit dl rm
usr_29.txt	20121	0644	edit dl rm
usr_30.txt	22658	0644	edit dl rm
usr_31.txt	10399	0644	edit dl rm
usr_32.txt	5378	0644	edit dl rm
usr_40.txt	23195	0644	edit dl rm
usr_41.txt	97378	0644	edit dl rm
usr_42.txt	13853	0644	edit dl rm
usr_43.txt	7409	0644	edit dl rm
usr_44.txt	28948	0644	edit dl rm
usr_45.txt	17688	0644	edit dl rm
usr_46.txt	7096	0644	edit dl rm
usr_90.txt	16836	0644	edit dl rm
usr_toc.txt	9505	0644	edit dl rm
various.txt	31097	0644	edit dl rm
version4.txt	13911	0644	edit dl rm
version5.txt	308532	0644	edit dl rm
version6.txt	576940	0644	edit dl rm
version7.txt	674701	0644	edit dl rm
version8.txt	1940307	0644	edit dl rm
vim9.txt	57158	0644	edit dl rm
visual.txt	21794	0644	edit dl rm
vi_diff.txt	57428	0644	edit dl rm
windows.txt	55732	0644	edit dl rm
workshop.txt	371	0644	edit dl rm

Edit: /usr/share/vim/vim82/doc/usr_29.txt (20121B)

*usr_29.txt*	For Vim version 8.2.  Last change: 2016 Feb 27

VIM USER MANUAL - by Bram Moolenaar

Moving through programs

The creator of Vim is a computer programmer.  It's no surprise that Vim
contains many features to aid in writing programs.  Jump around to find where
identifiers are defined and used.  Preview declarations in a separate window.
There is more in the next chapter.

|29.1|	Using tags
|29.2|	The preview window
|29.3|	Moving through a program
|29.4|	Finding global identifiers
|29.5|	Finding local identifiers

==============================================================================
*29.1*	Using tags

What is a tag?  It is a location where an identifier is defined.  An example
is a function definition in a C or C++ program.  A list of tags is kept in a
tags file.  This can be used by Vim to directly jump from any place to the
tag, the place where an identifier is defined.
   To generate the tags file for all C files in the current directory, use the
following command: >

ctags *.c

"ctags" is a separate program.  Most Unix systems already have it installed.
If you do not have it yet, you can find Exuberant ctags here:

http://ctags.sf.net ~

Now when you are in Vim and you want to go to a function definition, you can
jump to it by using the following command: >

:tag startlist

This command will find the function "startlist" even if it is in another file.
   The CTRL-] command jumps to the tag of the word that is under the cursor.
This makes it easy to explore a tangle of C code.  Suppose, for example, that
you are in the function "write_block".  You can see that it calls
"write_line".  But what does "write_line" do?  By placing the cursor on the
call to "write_line" and pressing CTRL-], you jump to the definition of this
function.
   The "write_line" function calls "write_char".  You need to figure out what
it does.  So you position the cursor over the call to "write_char" and press
CTRL-].  Now you are at the definition of "write_char".

+-------------------------------------+
	|void write_block(char **s; int cnt)  |
	|{				      |
	|   int i;			      |
	|   for (i = 0; i < cnt; ++i)	      |
	|      write_line(s[i]);	      |
	|}	    |			      |
	+-----------|-------------------------+
		    |
	     CTRL-] |
		    |	 +----------------------------+
		    +--> |void write_line(char *s)    |
			 |{			      |
			 |   while (*s != 0)	      |
			 |	write_char(*s++);     |
			 |}	  |		      |
			 +--------|-------------------+
				  |
			   CTRL-] |
				  |    +------------------------------------+
				  +--> |void write_char(char c)		    |
				       |{				    |
				       |    putchar((int)(unsigned char)c); |
				       |}				    |
				       +------------------------------------+

The ":tags" command shows the list of tags that you traversed through:

:tags
	  # TO tag	   FROM line  in file/text ~
	  1  1 write_line	   8  write_block.c ~
	  2  1 write_char	   7  write_line.c ~
	> ~
>
Now to go back.  The CTRL-T command goes to the preceding tag.  In the example
above you get back to the "write_line" function, in the call to "write_char".
   This command takes a count argument that indicates how many tags to jump
back.  You have gone forward, and now back.  Let's go forward again.  The
following command goes to the tag on top of the list: >

:tag

You can prefix it with a count and jump forward that many tags.  For example:
":3tag".  CTRL-T also can be preceded with a count.
   These commands thus allow you to go down a call tree with CTRL-] and back
up again with CTRL-T.  Use ":tags" to find out where you are.

SPLIT WINDOWS

The ":tag" command replaces the file in the current window with the one
containing the new function.  But suppose you want to see not only the old
function but also the new one?  You can split the window using the ":split"
command followed by the ":tag" command.  Vim has a shorthand command that does
both: >
	:stag tagname

To split the current window and jump to the tag under the cursor use this
command: >

CTRL-W ]

If a count is specified, the new window will be that many lines high.

MORE TAGS FILES

When you have files in many directories, you can create a tags file in each of
them.  Vim will then only be able to jump to tags within that directory.
   To find more tags files, set the 'tags' option to include all the relevant
tags files.  Example: >

:set tags=./tags,./../tags,./*/tags

This finds a tags file in the same directory as the current file, one
directory level higher and in all subdirectories.
   This is quite a number of tags files, but it may still not be enough.  For
example, when editing a file in "~/proj/src", you will not find the tags file
"~/proj/sub/tags".  For this situation Vim offers to search a whole directory
tree for tags files.  Example: >

:set tags=~/proj/**/tags

ONE TAGS FILE

When Vim has to search many places for tags files, you can hear the disk
rattling.  It may get a bit slow.  In that case it's better to spend this
time while generating one big tags file.  You might do this overnight.
   This requires the Exuberant ctags program, mentioned above.  It offers an
argument to search a whole directory tree: >

cd ~/proj
	ctags -R .

The nice thing about this is that Exuberant ctags recognizes various file
types.  Thus this doesn't work just for C and C++ programs, also for Eiffel
and even Vim scripts.  See the ctags documentation to tune this.
   Now you only need to tell Vim where your big tags file is: >

:set tags=~/proj/tags

MULTIPLE MATCHES

When a function is defined multiple times (or a method in several classes),
the ":tag" command will jump to the first one.  If there is a match in the
current file, that one is used first.
   You can now jump to other matches for the same tag with: >

:tnext

Repeat this to find further matches.  If there are many, you can select which
one to jump to: >

:tselect tagname

Vim will present you with a list of choices:

# pri kind tag	       file ~
	  1 F	f    mch_init	       os_amiga.c ~
		       mch_init() ~
	  2 F	f    mch_init	       os_mac.c ~
		       mch_init() ~
	  3 F	f    mch_init	       os_msdos.c ~
		       mch_init(void) ~
	  4 F	f    mch_init	       os_riscos.c ~
		       mch_init() ~
	Enter nr of choice (<CR> to abort):  ~

You can now enter the number (in the first column) of the match that you would
like to jump to.  The information in the other columns give you a good idea of
where the match is defined.

To move between the matching tags, these commands can be used:

:tfirst			go to first match
	:[count]tprevious	go to [count] previous match
	:[count]tnext		go to [count] next match
	:tlast			go to last match

If [count] is omitted then one is used.

GUESSING TAG NAMES

Command line completion is a good way to avoid typing a long tag name.  Just
type the first bit and press <Tab>: >

:tag write_<Tab>

You will get the first match.  If it's not the one you want, press <Tab> until
you find the right one.
   Sometimes you only know part of the name of a function.  Or you have many
tags that start with the same string, but end differently.  Then you can tell
Vim to use a pattern to find the tag.
   Suppose you want to jump to a tag that contains "block".  First type
this: >

:tag /block

Now use command line completion: press <Tab>.  Vim will find all tags that
contain "block" and use the first match.
   The "/" before a tag name tells Vim that what follows is not a literal tag
name, but a pattern.  You can use all the items for search patterns here.  For
example, suppose you want to select a tag that starts with "write_": >

:tselect /^write_

The "^" specifies that the tag starts with "write_".  Otherwise it would also
be found halfway a tag name.  Similarly "$" at the end makes sure the pattern
matches until the end of a tag.

A TAGS BROWSER

Since CTRL-] takes you to the definition of the identifier under the cursor,
you can use a list of identifier names as a table of contents.  Here is an
example.
   First create a list of identifiers (this requires Exuberant ctags): >

ctags --c-types=f -f functions *.c

Now start Vim without a file, and edit this file in Vim, in a vertically split
window: >

vim
	:vsplit functions

The window contains a list of all the functions.  There is some more stuff,
but you can ignore that.  Do ":setlocal ts=99" to clean it up a bit.
   In this window, define a mapping: >

:nnoremap <buffer> <CR> 0ye<C-W>w:tag <C-R>"<CR>

Move the cursor to the line that contains the function you want to go to.
Now press <Enter>.  Vim will go to the other window and jump to the selected
function.