--- /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