Adding upstream version 2:8.1.0875.upstream/2%8.1.0875upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 487 insertions, 0 deletions

diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt
new file mode 100644
index 0000000..ba0f1d5
--- /dev/null
+++ b/runtime/doc/if_cscop.txt
@@ -0,0 +1,487 @@
+*if_cscop.txt*  For Vim version 8.1.  Last change: 2018 Jan 21
+
+
+		  VIM REFERENCE MANUAL    by Andy Kahn
+
+							*cscope* *Cscope*
+This document explains how to use Vim's cscope interface.
+
+Cscope is a tool like ctags, but think of it as ctags on steroids since it
+does a lot more than what ctags provides.  In Vim, jumping to a result from
+a cscope query is just like jumping to any tag; it is saved on the tag stack
+so that with the right keyboard mappings, you can jump back and forth between
+functions as you normally would with |tags|.
+
+1. Cscope introduction		|cscope-intro|
+2. Cscope related commands	|cscope-commands|
+3. Cscope options		|cscope-options|
+4. How to use cscope in Vim	|cscope-howtouse|
+5. Limitations			|cscope-limitations|
+6. Suggested usage		|cscope-suggestions|
+7. Availability & Information	|cscope-info|
+
+This is currently for Unix and Win32 only.
+{Vi does not have any of these commands}
+
+==============================================================================
+1. Cscope introduction					*cscope-intro*
+
+The following text is taken from a version of the cscope man page:
+
+				    -----
+
+  Cscope is an interactive screen-oriented tool that helps you:
+
+       Learn how a C program works without endless flipping through a thick
+       listing.
+
+       Locate the section of code to change to fix a bug without having to
+       learn the entire program.
+
+       Examine the effect of a proposed change such as adding a value to an
+       enum variable.
+
+       Verify that a change has been made in all source files such as adding
+       an argument to an existing function.
+
+       Rename a global variable in all source files.
+
+       Change a constant to a preprocessor symbol in selected lines of files.
+
+  It is designed to answer questions like:
+       Where is this symbol used?
+       Where is it defined?
+       Where did this variable get its value?
+       What is this global symbol's definition?
+       Where is this function in the source files?
+       What functions call this function?
+       What functions are called by this function?
+       Where does the message "out of space" come from?
+       Where is this source file in the directory structure?
+       What files include this header file?
+
+  Cscope answers these questions from a symbol database that it builds the
+  first time it is used on the source files.  On a subsequent call, cscope
+  rebuilds the database only if a source file has changed or the list of
+  source files is different.  When the database is rebuilt the data for the
+  unchanged files is copied from the old database, which makes rebuilding
+  much faster than the initial build.
+
+				    -----
+
+When cscope is normally invoked, you will get a full-screen selection
+screen allowing you to make a query for one of the above questions.
+However, once a match is found to your query and you have entered your
+text editor to edit the source file containing match, you cannot simply
+jump from tag to tag as you normally would with vi's Ctrl-] or :tag
+command.
+
+Vim's cscope interface is done by invoking cscope with its line-oriented
+interface, and then parsing the output returned from a query.  The end
+result is that cscope query results become just like regular tags, so
+you can jump to them just like you do with normal tags (Ctrl-] or :tag)
+and then go back by popping off the tagstack with Ctrl-T.  (Please note
+however, that you don't actually jump to a cscope tag simply by doing
+Ctrl-] or :tag without remapping these commands or setting an option.
+See the remaining sections on how the cscope interface works and for
+suggested use.)
+
+
+==============================================================================
+2. Cscope related commands				*cscope-commands*
+
+		*:cscope* *:cs* *:scs* *:scscope* *E259* *E262* *E561* *E560*
+All cscope commands are accessed through suboptions to the cscope commands.
+	`:cscope` or `:cs` is the main command
+	`:scscope` or `:scs` does the same and splits the window
+	`:lcscope` or `:lcs` uses the location list, see |:lcscope|
+
+The available subcommands are:
+
+			*E563* *E564* *E566* *E568* *E622* *E623* *E625*
+			*E626* *E609*
+    add   : Add a new cscope database/connection.
+
+	USAGE	:cs add {file|dir} [pre-path] [flags]
+
+	    [pre-path] is the pathname used with the -P command to cscope.
+
+	    [flags] are any additional flags you want to pass to cscope.
+
+	EXAMPLES >
+	    :cscope add /usr/local/cdb/cscope.out
+	    :cscope add /projects/vim/cscope.out /usr/local/vim
+	    :cscope add cscope.out /usr/local/vim -C
+<
+				      *cscope-find* *cs-find* *E567*
+    find  : Query cscope.  All cscope query options are available
+	    except option #5 ("Change this grep pattern").
+
+	USAGE	:cs find {querytype} {name}
+
+	    {querytype} corresponds to the actual cscope line
+	    interface numbers as well as default nvi commands:
+
+		0 or s: Find this C symbol
+		1 or g: Find this definition
+		2 or d: Find functions called by this function
+		3 or c: Find functions calling this function
+		4 or t: Find this text string
+		6 or e: Find this egrep pattern
+		7 or f: Find this file
+		8 or i: Find files #including this file
+		9 or a: Find places where this symbol is assigned a value
+
+	For all types, except 4 and 6, leading white space for {name} is
+	removed.  For 4 and 6 there is exactly one space between {querytype}
+	and {name}.  Further white space is included in {name}.
+
+	EXAMPLES >
+	    :cscope find c vim_free
+	    :cscope find 3  vim_free
+<
+	    These two examples perform the same query: functions calling
+	    "vim_free". >
+
+	    :cscope find t initOnce
+	    :cscope find t  initOnce
+<
+	    The first one searches for the text "initOnce", the second one for
+	    " initOnce". >
+
+	    :cscope find 0 DEFAULT_TERM
+<
+	    Executing this example on the source code for Vim 5.1 produces the
+	    following output:
+
+	    Cscope tag: DEFAULT_TERM
+	       #   line  filename / context / line
+	       1   1009  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"amiga"
+	       2   1013  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"win32"
+	       3   1017  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"pcterm"
+	       4   1021  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"ansi"
+	       5   1025  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"vt52"
+	       6   1029  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"os2ansi"
+	       7   1033  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"ansi"
+	       8   1037  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 # undef DEFAULT_TERM
+	       9   1038  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"beos-ansi"
+	      10   1042  vim-5.1-gtk/src/term.c <<GLOBAL>>
+			 #define DEFAULT_TERM (char_u *)"mac-ansi"
+	      11   1335  vim-5.1-gtk/src/term.c <<set_termname>>
+			 term = DEFAULT_TERM;
+	      12   1459  vim-5.1-gtk/src/term.c <<set_termname>>
+			 if (STRCMP(term, DEFAULT_TERM))
+	      13   1826  vim-5.1-gtk/src/term.c <<termcapinit>>
+			 term = DEFAULT_TERM;
+	      14   1833  vim-5.1-gtk/src/term.c <<termcapinit>>
+			 term = DEFAULT_TERM;
+	      15   3635  vim-5.1-gtk/src/term.c <<update_tcap>>
+			 p = find_builtin_term(DEFAULT_TERM);
+	    Enter nr of choice (<CR> to abort):
+
+	    The output shows several pieces of information:
+	    1. The tag number (there are 15 in this example).
+	    2. The line number where the tag occurs.
+	    3. The filename where the tag occurs.
+	    4. The context of the tag (e.g., global, or the function name).
+	    5. The line from the file itself.
+
+    help  : Show a brief synopsis.
+
+	    USAGE   :cs help
+
+							*E261*
+    kill  : Kill a cscope connection (or kill all cscope connections).
+
+	    USAGE   :cs kill {num|partial_name}
+
+	    To kill a cscope connection, the connection number or a partial
+	    name must be specified.  The partial name is simply any part of
+	    the pathname of the cscope database.  Kill a cscope connection
+	    using the partial name with caution!
+
+	    If the specified connection number is -1, then _ALL_ cscope
+	    connections will be killed.
+
+    reset : Reinit all cscope connections.
+
+	    USAGE   :cs reset
+
+    show  : Show cscope connections.
+
+	    USAGE   :cs show
+
+							*:lcscope* *:lcs*
+This command is same as the ":cscope" command, except when the
+'cscopequickfix' option is set, the location list for the current window is
+used instead of the quickfix list to show the cscope results.
+
+							*:cstag* *E257* *E562*
+If you use cscope as well as ctags, |:cstag| allows you to search one or
+the other before making a jump.  For example, you can choose to first
+search your cscope database(s) for a match, and if one is not found, then
+your tags file(s) will be searched.  The order in which this happens
+is determined by the value of |csto|.  See |cscope-options| for more
+details.
+
+|:cstag| performs the equivalent of ":cs find g" on the identifier when
+searching through the cscope database(s).
+
+|:cstag| performs the equivalent of |:tjump| on the identifier when searching
+through your tags file(s).
+
+
+==============================================================================
+3. Cscope options					*cscope-options*
+
+Use the |:set| command to set all cscope options.  Ideally, you would do
+this in one of your startup files (e.g., .vimrc).  Some cscope related
+variables are only valid within |.vimrc|.  Setting them after vim has
+started will have no effect!
+
+							*cscopeprg* *csprg*
+'cscopeprg' specifies the command to execute cscope.  The default is
+"cscope".  For example: >
+	:set csprg=/usr/local/bin/cscope
+<
+					    *cscopequickfix* *csqf* *E469*
+{not available when compiled without the |+quickfix| feature}
+'cscopequickfix' specifies whether to use quickfix window to show cscope
+results.  This is a list of comma-separated values. Each item consists of
+|cscope-find| command (s, g, d, c, t, e, f, i or a) and flag (+, - or 0).
+'+' indicates that results must be appended to quickfix window,
+'-' implies previous results clearance, '0' or command absence - don't use
+quickfix.  Search is performed from start until first command occurrence.
+The default value is "" (don't use quickfix anyway).  The following value
+seems to be useful: >
+	:set cscopequickfix=s-,c-,d-,i-,t-,e-,a-
+<
+							*cscopetag* *cst*
+If 'cscopetag' is set, the commands ":tag" and CTRL-] as well as "vim -t"
+will always use |:cstag| instead of the default :tag behavior.  Effectively,
+by setting 'cst', you will always search your cscope databases as well as
+your tag files.  The default is off.  Examples: >
+	:set cst
+	:set nocst
+<
+							*cscoperelative* *csre*
+If 'cscoperelative' is set, then in absence of a prefix given to cscope
+(prefix is the argument of -P option of cscope), basename of cscope.out
+location (usually the project root directory) will be used as the prefix
+to construct an absolute path.  The default is off.  Note: This option is
+only effective when cscope (cscopeprg) is initialized without a prefix
+path (-P).  Examples: >
+	:set csre
+	:set nocsre
+<
+							*cscopetagorder* *csto*
+The value of 'csto' determines the order in which |:cstag| performs a search.
+If 'csto' is set to zero, cscope database(s) are searched first, followed
+by tag file(s) if cscope did not return any matches.  If 'csto' is set to
+one, tag file(s) are searched before cscope database(s).  The default is zero.
+Examples: >
+	:set csto=0
+	:set csto=1
+<
+						*cscopeverbose* *csverb*
+If 'cscopeverbose' is not set (the default), messages will not be printed
+indicating success or failure when adding a cscope database.  Ideally, you
+should reset this option in your |.vimrc| before adding any cscope databases,
+and after adding them, set it.  From then on, when you add more databases
+within Vim, you will get a (hopefully) useful message should the database fail
+to be added.  Examples: >
+	:set csverb
+	:set nocsverb
+<
+						      *cscopepathcomp* *cspc*
+The value of 'cspc' determines how many components of a file's path to
+display.  With the default value of zero the entire path will be displayed.
+The value one will display only the filename with no path.  Other values
+display that many components.  For example: >
+	:set cspc=3
+will display the last 3 components of the file's path, including the file
+name itself.
+
+==============================================================================
+4. How to use cscope in Vim				*cscope-howtouse*
+
+The first thing you need to do is to build a cscope database for your
+source files.  For the most basic case, simply do "cscope -b".  Please
+refer to the cscope man page for more details.
+
+Assuming you have a cscope database, you need to "add" the database to Vim.
+This establishes a cscope "connection" and makes it available for Vim to use.
+You can do this in your .vimrc file, or you can do it manually after starting
+vim.  For example, to add the cscope database "cscope.out", you would do:
+
+	:cs add cscope.out
+
+You can double-check the result of this by executing ":cs show".  This will
+produce output which looks like this:
+
+ # pid	  database name			      prepend path
+ 0 28806  cscope.out			      <none>
+
+Note:
+Because of the Microsoft RTL limitations, Win32 version shows 0 instead
+of the real pid.
+
+Once a cscope connection is established, you can make queries to cscope and
+the results will be printed to you.  Queries are made using the command
+":cs find".  For example:
+
+	:cs find g ALIGN_SIZE
+
+This can get a little cumbersome since one ends up doing a significant
+amount of typing.  Fortunately, there are ways around this by mapping
+shortcut keys.  See |cscope-suggestions| for suggested usage.
+
+If the results return only one match, you will automatically be taken to it.
+If there is more than one match, you will be given a selection screen to pick
+the match you want to go to.  After you have jumped to the new location,
+simply hit Ctrl-T to get back to the previous one.
+
+
+==============================================================================
+5. Limitations						*cscope-limitations*
+
+Cscope support for Vim is only available on systems that support these four
+system calls: fork(), pipe(), execl(), waitpid().  This means it is mostly
+limited to Unix systems.
+
+Additionally Cscope support works for Win32.  For more information and a
+cscope version for Win32 see:
+
+	http://iamphet.nm.ru/cscope/index.html
+
+The DJGPP-built version from http://cscope.sourceforge.net is known to not
+work with Vim.
+
+Hard-coded limitation: doing a |:tjump| when |:cstag| searches the tag files
+is not configurable (e.g., you can't do a tselect instead).
+
+==============================================================================
+6. Suggested usage					*cscope-suggestions*
+
+Put these entries in your .vimrc (adjust the pathname accordingly to your
+setup): >
+
+	if has("cscope")
+		set csprg=/usr/local/bin/cscope
+		set csto=0
+		set cst
+		set nocsverb
+		" add any database in current directory
+		if filereadable("cscope.out")
+		    cs add cscope.out
+		" else add database pointed to by environment
+		elseif $CSCOPE_DB != ""
+		    cs add $CSCOPE_DB
+		endif
+		set csverb
+	endif
+
+By setting 'cscopetag', we have effectively replaced all instances of the :tag
+command with :cstag.  This includes :tag, Ctrl-], and "vim -t".  In doing
+this, the regular tag command not only searches your ctags generated tag
+files, but your cscope databases as well.
+
+Some users may want to keep the regular tag behavior and have a different
+shortcut to access :cstag.  For example, one could map Ctrl-_  (underscore)
+to :cstag with the following command: >
+
+	map <C-_> :cstag <C-R>=expand("<cword>")<CR><CR>
+
+A couple of very commonly used cscope queries (using ":cs find") is to
+find all functions calling a certain function and to find all occurrences
+of a particular C symbol.  To do this, you can use these mappings as an
+example: >
+
+	map g<C-]> :cs find 3 <C-R>=expand("<cword>")<CR><CR>
+	map g<C-\> :cs find 0 <C-R>=expand("<cword>")<CR><CR>
+
+These mappings for Ctrl-] (right bracket) and Ctrl-\ (backslash) allow you to
+place your cursor over the function name or C symbol and quickly query cscope
+for any matches.
+
+Or you may use the following scheme, inspired by Vim/Cscope tutorial from
+Cscope Home Page (http://cscope.sourceforge.net/): >
+
+	nmap <C-_>s :cs find s <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>g :cs find g <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>c :cs find c <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>t :cs find t <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>e :cs find e <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>f :cs find f <C-R>=expand("<cfile>")<CR><CR>
+	nmap <C-_>i :cs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
+	nmap <C-_>d :cs find d <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-_>a :cs find a <C-R>=expand("<cword>")<CR><CR>
+
+	" Using 'CTRL-spacebar' then a search type makes the vim window
+	" split horizontally, with search result displayed in
+	" the new window.
+
+	nmap <C-Space>s :scs find s <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>g :scs find g <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>c :scs find c <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>t :scs find t <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>e :scs find e <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>f :scs find f <C-R>=expand("<cfile>")<CR><CR>
+	nmap <C-Space>i :scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
+	nmap <C-Space>d :scs find d <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space>a :scs find a <C-R>=expand("<cword>")<CR><CR>
+
+	" Hitting CTRL-space *twice* before the search type does a vertical
+	" split instead of a horizontal one
+
+	nmap <C-Space><C-Space>s
+		\:vert scs find s <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>g
+		\:vert scs find g <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>c
+		\:vert scs find c <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>t
+		\:vert scs find t <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>e
+		\:vert scs find e <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>i
+		\:vert scs find i ^<C-R>=expand("<cfile>")<CR>$<CR>
+	nmap <C-Space><C-Space>d
+		\:vert scs find d <C-R>=expand("<cword>")<CR><CR>
+	nmap <C-Space><C-Space>a
+		\:vert scs find a <C-R>=expand("<cword>")<CR><CR>
+
+==============================================================================
+7. Cscope availability and information			*cscope-info*
+
+If you do not already have cscope (it did not come with your compiler
+license or OS distribution), then you can download it for free from:
+	http://cscope.sourceforge.net/
+This is released by SCO under the BSD license.
+
+In Solaris 2.x, if you have the C compiler license, you will also have
+cscope.  Both are usually located under /opt/SUNWspro/bin
+
+There is source to an older version of a cscope clone (called "cs") available
+on the net.  Due to various reasons, this is not supported with Vim.
+
+The cscope interface/support for Vim was originally written by
+Andy Kahn <ackahn@netapp.com>.  The original structure (as well as a tiny
+bit of code) was adapted from the cscope interface in nvi.
+							*cscope-win32*
+For a cscope version for Win32 see (seems abandoned):
+	https://code.google.com/archive/p/cscope-win32/
+
+Win32 support was added by Sergey Khorev <sergey.khorev@gmail.com>.  Contact
+him if you have Win32-specific issues.
+
+ vim:tw=78:ts=8:noet:ft=help:norl: