Imported Upstream version 15.8aupstream/15.8aupstream

1 files changed, 574 insertions, 0 deletions

diff --git a/doc/xcscope.1 b/doc/xcscope.1
new file mode 100644
index 0000000..fa4199c
--- /dev/null
+++ b/doc/xcscope.1
@@ -0,0 +1,574 @@
+'\" 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>
+.\"
+
+.de EX
+.sp
+.nf
+.ft CW
+..
+.de EE
+.ft R
+.fi
+.sp
+..
+
+.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:
+.EX
+	(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)
+.EE
+
+.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:
+
+.EX
+	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
+.EE
+
+.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:
+
+.EX
+	/users/jdoe/sources
+	/users/jdoe/sources/proj1
+	/users/jdoe/sources/proj2
+.EE
+
+.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:
+
+.TS
+lb li.
+C-c s s       Find symbol.
+C-c s d       Find global definition.
+C-c s g       Find global definition (alternate binding).
+C-c s G       Find global definition without prompting.
+C-c s c       Find functions calling a function.
+C-c s C       Find called functions (list functions called
+C-c s t       Find text string.
+C-c s e       Find egrep pattern.
+C-c s f       Find a file.
+C-c s i       Find files #including a file.
+.TE
+
+These pertain to navigation through the search results:
+
+.TS
+lb li.
+C-c s b       Display *cscope* buffer.
+C-c s B       Auto display *cscope* buffer toggle.
+C-c s n       Next symbol.
+C-c s N       Next file.
+C-c s p       Previous symbol.
+C-c s P       Previous file.
+C-c s u       Pop mark.
+.TE
+
+.P
+These pertain to setting and unsetting the variable,
+`cscope-initial-directory', (location searched for the cscope database
+directory):
+
+.TS
+lb li.
+C-c s a       Set initial directory.
+C-c s A       Unset initial directory.
+.TE
+
+.P
+These pertain to cscope database maintenance:
+
+.TS
+lb li.
+C-c s L       Create list of files to index.
+C-c s I       Create list and index.
+C-c s E       Edit list of files to index.
+C-c s W       T{
+Locate this buffer's cscope directory.
+.br
+("W" -> "where")
+T}
+C-c s S       T{
+Locate this buffer's cscope directory.
+.br
+("S" --> "show")
+T}
+C-c s T       T{
+Locate this buffer's cscope directory.
+("T" --> "tell")
+T}
+C-c s D       Dired this buffer's directory.
+.TE
+
+.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:
+
+.EX
+     cd top-level-directory    # or wherever
+     rm -f cscope.out          # not always necessary
+     cscope -b
+.EE
+
+.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:
+
+.EX
+     cd some-directory         # wherever cscope.files exists
+     rm -f cscope.out          # not always necessary
+     cscope -b
+.EE
+
+.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:
+
+.EX
+     ( DBDIR )
+     ( DBDIR ( OPTIONS ) )
+     ( t )
+     t
+.EE
+
+.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':
+
+.EX
+	(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") )
+		  )
+		))
+.EE
+
+.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"
+
+.EX
+     cscope-file-face
+     cscope-function-face
+     cscope-line-number-face
+     cscope-line-face
+     cscope-mouse-face
+.EE
+
+.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.