diff -rU4 -N -p cscope-15.5/doc/Makefile.in cscope-15.5-xcscope/doc/Makefile.in --- cscope-15.5/doc/Makefile.in 2003-09-04 12:51:25.000000000 -0400 +++ cscope-15.5-xcscope/doc/Makefile.in 2004-07-20 13:49:11.000000000 -0400 @@ -129,9 +129,9 @@ sbindir = @sbindir@ sharedstatedir = @sharedstatedir@ sysconfdir = @sysconfdir@ target_alias = @target_alias@ -man_MANS = cscope.1 +man_MANS = cscope.1 xcscope.1 EXTRA_DIST = $(man_MANS) subdir = doc mkinstalldirs = $(SHELL) $(top_srcdir)/mkinstalldirs CONFIG_HEADER = $(top_builddir)/config.h diff -rU4 -N -p cscope-15.5/doc/xcscope.1 cscope-15.5-xcscope/doc/xcscope.1 --- cscope-15.5/doc/xcscope.1 1969-12-31 19:00:00.000000000 -0500 +++ cscope-15.5-xcscope/doc/xcscope.1 2004-07-20 13:47:48.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 +.\" + +.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.