1Cscope Notes:
2
3The nvi tags structure has been reworked to handle the notion of multiple
4locations per tag.  This supports cscope, which returns multiple locations
5per query.  It will hopefully support ctags programs that create databases
6with multiple locations per tag as well.
7
8There is now a list of "tag queues" chained from each screen.  Each tag
9queue has one or more "tag locations".
10
11   +----+    +----+	+----+     +----+
12   | EP | -> | Q1 | <-- | T1 | <-- | T2 |
13   +----+    +----+ --> +----+ --> +----+
14  	     |
15  	     +----+     +----+
16  	     | Q2 | <-- | T1 |
17  	     +----+ --> +----+
18  	     |
19  	     +----+	+----+
20  	     | Q3 | <-- | T1 |
21  	     +----+ --> +----+
22
23In the above diagram, each "Q" is a "tag queue", and each "T" is a
24tag location.  Generally, the commands:
25
26	:tag			create a new Q
27	^[			create a new Q
28	:cscope find		create a new Q
29	:tagnext		move to the next T
30	:tagprev		move to the previous T
31	:tagpop			discard one or more Q's
32	^T			discard the most recent Q
33	:tagtop			discard all Q's
34
35More specifically:
36
37:cs[cope] a[dd] cscope-dir
38
39	Attach to the cscope database in cscope-dir.
40
41:cs[cope] f[ind] c|d|e|f|g|i|s|t buffer|pattern
42
43	Query all attached cscopes for the pattern.  The pattern is a
44	regular expression.  If the pattern is a double-quote character
45	followed by a valid buffer name (e.g., "t), then the contents
46	of the named buffer are used as the pattern.
47
48	c: find callers of name
49	d: find all function calls made from name
50	e: find pattern
51	f: find files with name as substring
52	g: find definition of name
53	i: find files #including name
54	s: find all uses of name
55	t: find assignments to name
56
57	The find command pushes the current location onto the tags stack,
58	and switches to the first location resulting from the query, if
59	the query returned at least one result.
60
61:cs[cope] h[elp] [command]
62
63	List the cscope commands, or usage help on one command.
64
65:display c[onnections]
66
67	Display the list of cscope connections
68
69:display t[ags]
70
71	The tags display has been enhanced to display multiple tag
72	locations per tag query.
73
74:cs[cope] k[ill] #
75
76	Kill cscope connection number #.
77
78:cs[cope] r[eset]
79	Kill all attached cscopes.  Useful if one got hung but you don't
80	know which one.
81
82:tagn[ext][!]
83
84	Move to the next tag resulting from a query.
85
86:tagpr[ev][!]
87
88	Return to the previous tag resulting from a query.
89
90:tagp[op], ^T
91
92	Return to the previous tag group (no change).
93
94:tagt[op]
95
96	Discard all tag groups (no change).
97
98Suggested maps:
99
100	" ^N: move to the next tag
101	map ^N :tagnext^M
102	" ^P: move to the previous tag
103	map ^P :tagprev^M
104
105	" Tab+letter performs a C-Scope query on the current word.
106	" C-Scope 12.9 has a text-string query (type t).
107	" C-Scope 13.3 replaces it with an assignment query; hence a==t.
108	map <tab>a "tye:csc find t"t
109	map <tab>c "tye:csc find c"t
110	map <tab>d "tye:csc find d"t
111	map <tab>e "tye:csc find e"t
112	map <tab>f "tye:csc find f"t
113	map <tab>g "tye:csc find g"t
114	map <tab>i "tye:csc find i"t
115	map <tab>s "tye:csc find s"t
116	map <tab>t "tye:csc find t"t
117
118To start nvi with an initial set of cscope directories, use the environment
119variable CSCOPE_DIRS.  This variable should contain a <blank>-separated
120list of directories containing cscope databases.  (This MAY be changed to
121be an edit option, I haven't really decided, yet.)
122
123Each cscope directory must contain a file named "cscope.out" which is the
124main cscope database, or nvi will not attempt to connect to a cscope to
125handle requests for that database.
126
127The file "cscope.tpath" may contain a colon-separated directory search
128path which will be used to find the files reported by cscope.  If this
129cscope.tpath does not exist, then the paths are assumed to be relative to
130the cscope directory itself.  This is an extension to the standard cscope,
131but seems important enough to keep.
132
133=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
134Cscope Availability:
135
136UNIXWare System V Release 4.0 variants such as Sun Solaris 2.x
137(/opt/SUNWspro/bin) have version 11.5, and UNIXWare System V
138Release 4.1 has version 12.10 with an option for much faster
139searching.
140
141You can buy version 13.3 source with an unrestricted license
142for $400 from AT&T Software Solutions by calling +1-800-462-8146.
143