--- /dev/null	2007-05-12 17:40:21.471089444 -0400

+++ cscope-15.6/doc/xcscope.1	2007-05-25 09:45:31.000000000 -0400

@@ -0,0 +1,577 @@

+'\" t

+.\" The xcscope.el man page

+.\" Origionally written by Darryl Okahata, Apr 2000

+.\" 

+.\" Converted to a man page July 20, 2004 by Neil Horman <nhorman@redhat.com>

+.\"

+

+.PU

+.TH XCSCOPE.EL "1" "April 2000" "Darryl Okahata"

+.SH NAME

+xcscope.el - xemacs cscope lisp support package

+.SH DESCRIPTION

+xcscope is a lisp package for use in integrating cscope 

+functionality into xemacs

+.SH INSTALLATION

+.P

+ Installation steps:

+

+.P

+ 0. (It is, of course, assumed that cscope is already properly

+    installed on the current system.)

+.P

+ 1. Ensure that the location of cscope-indexer is located in your path

+

+.P

+ 2. Ensure that the location of xcscope.el is in the xemacs module load path

+

+.P

+ 3. Edit your ~/.emacs file to add the line:

+.P

+.BI      (require 'xcscope)

+

+.P

+5. If you intend to use xcscope.el often you can optionally edit your

+~/.emacs file to add keybindings that reduce the number of keystrokes

+required.  For example, the following will add "C-f#" keybindings,

+which are easier to type than the usual "C-c s" prefixed keybindings.

+Note that specifying "global-map" instead of "cscope:map" makes the

+keybindings available in all buffers:

+.nf

+	(define-key global-map [(ctrl f3)]  'cscope-set-initial-directory)

+	(define-key global-map [(ctrl f4)]  'cscope-unset-initial-directory)

+	(define-key global-map [(ctrl f5)]  'cscope-find-this-symbol)

+	(define-key global-map [(ctrl f6)]  'cscope-find-global-definition)

+	(define-key global-map [(ctrl f7)]

+		cscope-find-global-definition-no-prompting)

+	(define-key global-map [(ctrl f8)]  'cscope-pop-mark)

+	(define-key global-map [(ctrl f9)]  'cscope-next-symbol)

+	(define-key global-map [(ctrl f10)] 'cscope-next-file)

+	(define-key global-map [(ctrl f11)] 'cscope-prev-symbol)

+	(define-key global-map [(ctrl f12)] 'cscope-prev-file)

+	(define-key global-map [(meta f9)]  'cscope-display-buffer)

+	(define-key global-map [(meta f10)] 'cscope-display-buffer-toggle)

+.fi

+

+.P

+ 6. Restart (X)Emacs.  That's it.

+

+

+.SH USING THIS MODULE

+

+.SS * Basic usage:

+

+.P

+ If all of your C/C++/lex/yacc source files are in the same

+ directory, you can just start using this module.  If your files are

+ spread out over multiple directories, see "Advanced usage", below.

+

+.P

+ Just edit a source file, and use the pull-down or pop-up (button 3)

+ menus to select one of:

+

+.nf

+	Find symbol

+	Find global definition

+	Find called functions

+	Find functions calling a function

+	Find text string

+	Find egrep pattern

+	Find a file

+	Find files #including a file

+.fi

+

+.P

+The cscope database will be automatically created in the same directory 

+as the source files (assuming that you've never used cscope before), and

+a buffer will pop-up displaying the results.  You can then use button 2

+(the middle button) on the mouse to edit the selected file, or you can

+move the text cursor over a selection and press [Enter].

+

+.P

+Hopefully, the interface should be fairly intuitive.

+

+.SS * Locating the cscope databases:

+

+.P

+This module will first use the variable, `cscope-database-regexps',

+to search for a suitable database directory.  If a database location

+cannot be found using this variable then a search is begun at the

+variable, `cscope-initial-directory', if set, or the current

+directory otherwise.  If the directory is not a cscope database

+directory then the directory's parent, parent's parent, etc. is

+searched until a cscope database directory is found, or the root

+directory is reached.  If the root directory is reached, the current

+directory will be used.

+

+.P

+A cscope database directory is one in which EITHER a cscope database

+file (e.g., "cscope.out") OR a cscope file list (e.g.,

+"cscope.files") exists.  If only "cscope.files" exists, the

+corresponding "cscope.out" will be automatically created by cscope

+when a search is done.  By default, the cscope database file is called

+"cscope.out", but this can be changed (on a global basis) via the

+variable, `cscope-database-file'.  There is limited support for cscope

+databases that are named differently than that given by

+`cscope-database-file', using the variable, `cscope-database-regexps'.

+

+.P

+Note that the variable, `cscope-database-regexps', is generally not

+needed, as the normal hierarchical database search is sufficient

+for placing and/or locating the cscope databases.  However, there

+may be cases where it makes sense to place the cscope databases

+away from where the source files are kept; in this case, this

+variable is used to determine the mapping.  One use for this

+variable is when you want to share the database file with other

+users; in this case, the database may be located in a directory

+separate from the source files.  

+

+.P

+Setting the variable, `cscope-initial-directory', is useful when a

+search is to be expanded by specifying a cscope database directory

+that is a parent of the directory that this module would otherwise

+use.  For example, consider a project that contains the following

+cscope database directories:

+

+.nf

+	/users/jdoe/sources

+	/users/jdoe/sources/proj1

+	/users/jdoe/sources/proj2

+.fi

+

+.P

+If a search is initiated from a .c file in /users/jdoe/sources/proj1

+then (assuming the variable, `cscope-database-regexps', is not set)

+/users/jdoe/sources/proj1 will be used as the cscope data base directory.

+Only matches in files in /users/jdoe/sources/proj1 will be found.  This

+can be remedied by typing "C-c s a" and then "M-del" to remove single

+path element in order to use a cscope database directory of

+/users/jdoe/sources.  Normal searching can be restored by typing "C-c s A".

+

+

+

+.SS * Keybindings:

+

+.P

+All keybindings use the "C-c s" prefix, but are usable only while

+editing a source file, or in the cscope results buffer:

+

+.BI     "C-c s s         Find symbol."

+.TP

+.BI     "C-c s d         Find global definition."

+.TP

+.BI     "C-c s g         Find global definition (alternate binding)."

+.TP

+.BI     "C-c s G         Find global definition without prompting."

+.TP

+.BI     "C-c s c         Find functions calling a function."

+.TP

+.BI     "C-c s C         Find called functions (list functions called"

+.BI     "                from a function)."

+.TP

+.BI     "C-c s t         Find text string."

+.TP

+.BI     "C-c s e         Find egrep pattern."

+.TP

+.BI     "C-c s f         Find a file."

+.TP

+.BI     "C-c s i         Find files #including a file."

+

+.P

+These pertain to navigation through the search results:

+

+.P

+.BI     "C-c s b         Display *cscope* buffer."

+.TP

+.BI     "C-c s B         Auto display *cscope* buffer toggle."

+.TP

+.BI     "C-c s n         Next symbol."

+.TP

+.BI     "C-c s N         Next file."

+.TP

+.BI     "C-c s p         Previous symbol."

+.TP

+.BI     "C-c s P         Previous file."

+.TP

+.BI     "C-c s u         Pop mark."

+

+.P

+These pertain to setting and unsetting the variable,

+`cscope-initial-directory', (location searched for the cscope database

+directory):

+

+.P

+.BI     "C-c s a         Set initial directory."

+.TP

+.BI     "C-c s A         Unset initial directory."

+

+.P

+These pertain to cscope database maintenance:

+.P

+.BI     "C-c s L         Create list of files to index."

+.TP

+.BI     "C-c s I         Create list and index."

+.TP

+.BI     "C-c s E         Edit list of files to index."

+.TP

+.BI     "C-c s W          Locate this buffer's cscope directory"

+.BI     "                 ("

+"W" --> "where"

+.BI ")."

+.TP

+.BI     "C-c s S         Locate this buffer's cscope directory."

+.BI     "                 (alternate binding: "

+"S" --> "show"

+.BI ")."

+.TP

+.BI     "C-c s T         Locate this buffer's cscope directory."

+.BI     "                 (alternate binding: "

+"T" --> "tell"

+.BI ")."

+.TP

+.BI     "C-c s D         Dired this buffer's directory."

+

+.P

+.SS * Advanced usage:

+

+.P

+If the source files are spread out over multiple directories,

+you've got a few choices:

+

+.P

+[ NOTE: you will need to have the script, "cscope-indexer",

+properly installed in order for the following to work.  ]

+

+.P

+1. If all of the directories exist below a common directory

+(without any extraneous, unrelated subdirectories), you can tell

+this module to place the cscope database into the top-level,

+common directory.  This assumes that you do not have any cscope

+databases in any of the subdirectories.  If you do, you should

+delete them; otherwise, they will take precedence over the

+top-level database.

+

+.P

+If you do have cscope databases in any subdirectory, the

+following instructions may not work right.

+

+.P

+It's pretty easy to tell this module to use a top-level, common

+directory:

+

+.HP

+a. Make sure that the menu pick, "Cscope/Index recursively", is

+checked (the default value).

+

+.HP

+b. Select the menu pick, "Cscope/Create list and index", and

+specify the top-level directory.  This will run the script,

+"cscope-indexer", in the background, so you can do other

+things if indexing takes a long time.  A list of files to

+index will be created in "cscope.files", and the cscope

+database will be created in "cscope.out".

+

+.HP

+Once this has been done, you can then use the menu picks

+(described in "Basic usage", above) to search for symbols.

+

+.HP

+Note, however, that, if you add or delete source files, you'll

+have to either rebuild the database using the above procedure,

+or edit the file, "cscope.files" to add/delete the names of the

+source files.  To edit this file, you can use the menu pick,

+"Cscope/Edit list of files to index".

+

+.P

+2. If most of the files exist below a common directory, but a few

+are outside, you can use the menu pick, "Cscope/Create list of

+files to index", and specify the top-level directory.  Make sure

+that "Cscope/Index recursively", is checked before you do so,

+though.  You can then edit the list of files to index using the

+menu pick, "Cscope/Edit list of files to index".  Just edit the

+list to include any additional source files not already listed.

+

+.P

+Once you've created, edited, and saved the list, you can then

+use the menu picks described under "Basic usage", above, to

+search for symbols.  The first time you search, you will have to

+wait a while for cscope to fully index the source files, though.

+If you have a lot of source files, you may want to manually run

+cscope to build the database:

+

+.nf

+	cd top-level-directory    # or wherever

+	rm -f cscope.out          # not always necessary

+	cscope -b

+.fi

+

+.P

+ 3. If the source files are scattered in many different, unrelated

+    places, you'll have to manually create cscope.files and put a

+    list of all pathnames into it.  Then build the database using:

+

+.nf

+	cd some-directory         # wherever cscope.files exists

+	rm -f cscope.out          # not always necessary

+	cscope -b

+.fi

+

+.P

+Next, read the documentation for the variable,

+"cscope-database-regexps", and set it appropriately, such that

+the above-created cscope database will be referenced when you

+edit a related source file.

+

+.P

+Once this has been done, you can then use the menu picks

+described under "Basic usage", above, to search for symbols.

+

+.SS * Interesting configuration variables:

+

+.P

+.B "cscope-truncate-lines"

+.P

+This is the value of `truncate-lines' to use in cscope

+buffers; the default is the current setting of

+`truncate-lines'.  This variable exists because it can be

+easier to read cscope buffers with truncated lines, while

+other buffers do not have truncated lines.

+

+.P

+.B "cscope-use-relative-paths"

+.P

+If non-nil, use relative paths when creating the list of files

+to index.  The path is relative to the directory in which the

+cscope database will be created.  If nil, absolute paths will

+be used.  Absolute paths are good if you plan on moving the

+database to some other directory (if you do so, you'll

+probably also have to modify `cscope-database-regexps').

+Absolute paths may also be good if you share the database file

+with other users (you'll probably want to specify some

+automounted network path for this).

+

+.P

+.B "cscope-index-recursively"

+.P

+If non-nil, index files in the current directory and all

+subdirectories.  If nil, only files in the current directory

+are indexed.  This variable is only used when creating the

+list of files to index, or when creating the list of files and

+the corresponding cscope database.

+

+.P

+.B "cscope-name-line-width"

+.P

+The width of the combined "function name:line number" field in

+the cscope results buffer.  If negative, the field is

+left-justified.

+

+.P

+.B "cscope-do-not-update-database"

+.P

+If non-nil, never check and/or update the cscope database when

+searching.  Beware of setting this to non-nil, as this will

+disable automatic database creation, updating, and

+maintenance.

+

+.P

+.B "cscope-display-cscope-buffer" 

+.P

+If non-nil, display the *cscope* buffer after each search

+(default).  This variable can be set in order to reduce the

+number of keystrokes required to navigate through the matches.

+

+.P

+.B "cscope-database-regexps"

+.P

+List to force directory-to-cscope-database mappings.

+This is a list of `(REGEXP DBLIST [ DBLIST ... ])', where:

+

+.P

+.B "REGEXP" 

+is a regular expression matched against the current buffer's

+current directory.  The current buffer is typically some source file,

+and you're probably searching for some symbol in or related to this

+file.  Basically, this regexp is used to relate the current directory

+to a cscope database.  You need to start REGEXP with "^" if you want

+to match from the beginning of the current directory.

+

+.P

+.B "DBLIST" 

+is a list that contains one or more of:

+

+.nf

+	( DBDIR )

+	( DBDIR ( OPTIONS ) )

+	( t )

+	t

+.fi

+

+.P

+Here, 

+.B DBDIR 

+is a directory (or a file) that contains a cscope

+database.  If DBDIR is a directory, then it is expected that the

+cscope database, if present, has the filename given by the variable,

+`cscope-database-file'; if DBDIR is a file, then DBDIR is the path

+name to a cscope database file (which does not have to be the same as

+that given by `cscope-database-file').  If only DBDIR is specified,

+then that cscope database will be searched without any additional

+cscope command-line options.  If OPTIONS is given, then OPTIONS is a

+list of strings, where each string is a separate cscope command-line

+option.

+

+.P

+ In the case of "( t )", this specifies that the search is to use the

+ normal hierarchical database search.  This option is used to

+ explicitly search using the hierarchical database search either before

+ or after other cscope database directories.

+

+.P

+ If "t" is specified (not inside a list), this tells the searching

+ mechanism to stop searching if a match has been found (at the point

+ where "t" is encountered).  This is useful for those projects that

+ consist of many subprojects.  You can specify the most-used

+ subprojects first, followed by a "t", and then followed by a master

+ cscope database directory that covers all subprojects.  This will

+ cause the most-used subprojects to be searched first (hopefully

+ quickly), and the search will then stop if a match was found.  If not,

+ the search will continue using the master cscope database directory.

+

+.P

+ Here, `cscope-database-regexps' is generally not used, as the normal

+ hierarchical database search is sufficient for placing and/or locating

+ the cscope databases.  However, there may be cases where it makes

+ sense to place the cscope databases away from where the source files

+ are kept; in this case, this variable is used to determine the

+ mapping.

+

+.P

+ This module searches for the cscope databases by first using this

+ variable; if a database location cannot be found using this variable,

+ then the current directory is searched, then the parent, then the

+ parent's parent, until a cscope database directory is found, or the

+ root directory is reached.  If the root directory is reached, the

+ current directory will be used.

+

+.P

+A cscope database directory is one in which EITHER a cscope database

+file (e.g., "cscope.out") OR a cscope file list (e.g.,

+"cscope.files") exists.  If only "cscope.files" exists, the

+corresponding "cscope.out" will be automatically created by cscope

+when a search is done.  By default, the cscope database file is called

+"cscope.out", but this can be changed (on a global basis) via the

+variable, `cscope-database-file'.  There is limited support for cscope

+databases that are named differently than that given by

+`cscope-database-file', using the variable, `cscope-database-regexps'.

+

+.P

+Here is an example of `cscope-database-regexps':

+

+.nf

+	(setq cscope-database-regexps

+	      '(

+		( "^/users/jdoe/sources/proj1"

+		  ( t )

+		  ( "/users/jdoe/sources/proj2")

+		  ( "/users/jdoe/sources/proj3/mycscope.out")

+		  ( "/users/jdoe/sources/proj4")

+		  t

+		  ( "/some/master/directory" ("-d" "-I/usr/local/include") )

+		  )

+		( "^/users/jdoe/sources/gnome/"

+		  ( "/master/gnome/database" ("-d") )

+		  )

+		))

+.fi

+

+.P

+If the current buffer's directory matches the regexp,

+"^/users/jdoe/sources/proj1", then the following search will be

+done:

+

+.TP

+1. First, the normal hierarchical database search will be used to

+locate a cscope database.

+

+.TP

+2. Next, searches will be done using the cscope database

+directories, "/users/jdoe/sources/proj2",

+"/users/jdoe/sources/proj3/mycscope.out", and

+"/users/jdoe/sources/proj4".  Note that, instead of the file,

+"cscope.out", the file, "mycscope.out", will be used in the

+directory "/users/jdoe/sources/proj3".

+

+.TP

+3. If a match was found, searching will stop.

+

+.TP

+4. If a match was not found, searching will be done using

+"/some/master/directory", and the command-line options "-d"

+and "-I/usr/local/include" will be passed to cscope.

+

+.TP

+If the current buffer's directory matches the regexp,

+"^/users/jdoe/sources/gnome", then the following search will be

+done:

+

+.TP

+The search will be done only using the directory,

+"/master/gnome/database".  The "-d" option will be passed to

+cscope.

+

+.TP

+If the current buffer's directory does not match any of the above

+regexps, then only the normal hierarchical database search will be

+done.

+

+.P

+.SS * Other notes:

+

+.P

+1. The script, "cscope-indexer", uses a sed command to determine

+what is and is not a C/C++/lex/yacc source file.  It's idea of a

+source file may not correspond to yours.

+

+.P

+2. This module is called, "xcscope", because someone else has

+already written a "cscope.el" (although it's quite old).

+

+.SH KNOWN BUGS:

+

+.P

+1. Cannot handle whitespace in directory or file names.

+

+.P

+2. By default, colored faces are used to display results.  If you happen

+to use a black background, part of the results may be invisible

+(because the foreground color may be black, too).  There are at least

+two solutions for this:

+

+.TP

+.BI    "2a. Turn off colored faces, by setting `cscope-use-face' to `nil', eg:"

+.TP

+.BI            "(setq cscope-use-face nil)"

+

+.TP

+.BI   " 2b. Explicitly set colors for the faces used by cscope.  The faces are"

+

+.nf

+	cscope-file-face

+	cscope-function-face

+	cscope-line-number-face

+	cscope-line-face

+	cscope-mouse-face

+.fi

+

+.TP

+The face most likely to cause problems (e.g., black-on-black

+color) is `cscope-line-face'.

+

+.P

+3. The support for cscope databases different from that specified by

+`cscope-database-file' is quirky.  If the file does not exist, it

+will not be auto-created (unlike files names by

+`cscope-database-file').  You can manually force the file to be

+created by using touch(1) to create a zero-length file; the

+database will be created the next time a search is done.

--- cscope-15.6/doc/Makefile.in.orig	2006-09-30 11:14:57.000000000 -0400

+++ cscope-15.6/doc/Makefile.in	2007-05-25 09:46:04.000000000 -0400

@@ -148,7 +148,7 @@

 sharedstatedir = @sharedstatedir@

 sysconfdir = @sysconfdir@

 target_alias = @target_alias@

-man_MANS = cscope.1

+man_MANS = cscope.1 xcscope.1

 EXTRA_DIST = $(man_MANS)

 all: all-am