updated for version 7.0001
diff --git a/runtime/doc/if_cscop.txt b/runtime/doc/if_cscop.txt
new file mode 100644
index 0000000..44ff66c
--- /dev/null
+++ b/runtime/doc/if_cscop.txt
@@ -0,0 +1,474 @@
+*if_cscop.txt* For Vim version 7.0aa. Last change: 2004 Jan 17
+
+
+ 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 main cscope
+command ":cscope". The shortest abbreviation is ":cs". The ":scscope"
+command does the same and also splits the window (short: "scs").
+
+The available subcommands are:
+
+ *E563* *E564* *E566* *E568* *E569* *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*
+ *E565* *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
+
+ EXAMPLES >
+ :cscope find c vim_free
+ :cscope find 3 vim_free
+<
+ These two examples perform the same query. >
+
+ :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
+
+ *E260* *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
+
+ *: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 or i) 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: "s-,c-,d-,i-,t-,e-".
+
+ *cscopetag* *cst*
+If 'cscopetag' 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
+<
+ *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
+
+There are a couple of hard-coded limitations:
+
+ 1. The maximum number of cscope connections allowed is 8. Do you
+ really need more?
+
+ 2. 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>
+
+ " 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>
+
+ " 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>
+
+==============================================================================
+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.
+
+If you want a newer version of cscope, you will probably have to buy it.
+According to the (old) nvi documentation:
+
+ You can buy version 13.3 source with an unrestricted license
+ for $400 from AT&T Software Solutions by calling +1-800-462-8146.
+
+Also you can download cscope 13.x and mlcscope 14.x (multi-lingual cscope
+which supports C, C++, Java, lex, yacc, breakpoint listing, Ingres, and SDL)
+from World-Wide Exptools Open Source packages page:
+ http://www.bell-labs.com/project/wwexptools/packages.html
+
+In Solaris 2.x, if you have the C compiler license, you will also have
+cscope. Both are usually located under /opt/SUNWspro/bin
+
+SGI developers can also get it. Search for Cscope on this page:
+ http://freeware.sgi.com/index-by-alpha.html
+ https://toolbox.sgi.com/toolbox/utilities/cscope/
+The second one is for those who have a password for the SGI toolbox.
+
+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. Please report
+any problems, suggestions, patches, et al., you have for the usage of
+cscope within Vim to him.
+ *cscope-win32*
+For a cscope version for Win32 see: http://iamphet.nm.ru/cscope/index.html
+
+Win32 support was added by Sergey Khorev <khorev@softlab.ru>. Contact him
+if you have Win32-specific issues.
+
+ vim:tw=78:ts=8:ft=help:norl: