This is ecb.info, produced by makeinfo version 4.2 from ecb.texi. INFO-DIR-SECTION GNU Emacs Lisp START-INFO-DIR-ENTRY * ECB: (ecb). Emacs Code Browser END-INFO-DIR-ENTRY  File: ecb.info, Node: ecb-help, Next: ecb-eshell, Prev: ecb-download, Up: Customizable options Group ecb-help -------------- This group contains settings for the ECB online help: - User Option: help-html-path Path where the ECB online help in HTML format resides. This must be the location of the `ecb.html' which comes with the ECB distribution. If is installed by unpacking the archive available on the ECB website then this is the subdir `ecb-help-html-subdir' of the installation directory of ECB. If it is installed as XEmacs-package (e.g. via the package manager of XEmacs) then this is probably either the directory "../../html/" or "../../etc/ecb/html/" (both relative to the Elisp directory of ECB). The path can either be an absolute path or a path relative to the directory where the Elisp files of ECB are. Normally there should be no need to change this option! - User Option: help-info-path Path where the ECB online help in info format resides. This must be the location of the `ecb.info' which comes with the ECB distribution. If is installed by unpacking the archive available on the ECB website then this is the subdir `ecb-help-info-subdir' of the installation directory of ECB. If it is installed as XEmacs-package (e.g. via the package manager of XEmacs) then this is probably the directory "../../info/" (relative to the Elisp directory of ECB). The path can either be an absolute path or a path relative to the directory where the Elisp files of ECB are. Normally there should be no need to change this option! - User Option: show-help-format The format `ecb-show-help' shows its online help. Allowed values are 'info (for the Info format) and 'html (for HTML format). If the value is 'html then `browse-url-browser-function' says which browser is used. Note: If you got ECB as a standard XEmacs-package maybe the HTML-online-documentation is not included.  File: ecb.info, Node: ecb-eshell, Next: ecb-speedbar, Prev: ecb-help, Up: Customizable options Group ecb-eshell ---------------- This group contains settings for eshell integration within the ECB: - User Option: eshell-auto-activate Startup the eshell and display it in the compile-window. If current layout does not display a compile-window (see `ecb-compile-window-height') then nothing is done. - User Option: eshell-enlarge-when-eshell Enlarge the compile-window if it is selected by `eshell'. This takes only effect if the command `eshell' is called! - User Option: eshell-fit-window-to-command-output Fit the compile-window after an eshell-command to the output. This is done by the function `ecb-eshell-fit-window-to-output' which is added to `eshell-post-command-hook' ie. which is running autom. after each eshell-command. - User Option: eshell-synchronize Synchronize eshell with the default-directory of current source-buffer. The synchronization is done by `ecb-eshell-current-buffer-sync' which can be called interactively but normally it is called autom. by the `ecb-current-buffer-sync-hook-internal'.  File: ecb.info, Node: ecb-speedbar, Next: ecb-non-semantic, Prev: ecb-eshell, Up: Customizable options Group ecb-speedbar ------------------ - User Option: speedbar-before-activate-hook Hook running directly before ECB activates the integrated speedbar. For example this hook can be used to change the expansion-mode of the integrated speedbar via `speedbar-change-initial-expansion-list'. Example: (speedbar-change-initial-expansion-list "buffers").  File: ecb.info, Node: ecb-non-semantic, Next: ecb-winman, Prev: ecb-speedbar, Up: Customizable options Group ecb-non-semantic ---------------------- This group contains settings for parsing and displaying non-semantic files: - User Option: auto-save-before-etags-methods-rebuild Automatic saving of current buffer before rebuilding its methods. This option is only relevant for sources which are supported and parsed by etags (see `ecb-process-non-semantic-files'). Because etags is an external tool a source-buffer can only be reparsed if the buffer is saved to disk. So the command `ecb-rebuild-methods-buffer' checks for sources which are not supported by semantic or imenu if either this option is t or if the major-mode of the source-buffer is contained in this list: In both cases ECB saves the current source-buffer before it re-runs etags for reparsing the source. If nil or if the major-mode is not contained then no automatic saving will be done! For all source supported by semantic or by imenu this option takes no effect. - User Option: non-semantic-exclude-modes Exclude modes from parsing with imenu or etags. Per default, ECB tries to parse all file-types not supported by semantic with imenu or etags or some other method (for details see the option `ecb-non-semantic-parsing-function'). If a file-type can not be parsed by semantic, imenu or etags than this simply results in an empty method-buffer for this file. But nevertheless you will get a message "Sorry, no support for a file of that extension" which comes from the speedbar-library and can not switched off. Therefore if a `major-mode' is known as not parse-able by semantic, imenu or etags it can be added to this option and then it will be excluded from being tried to parsed. - User Option: non-semantic-methods-initial-expand Initially expand all tags for not by semantic supported sources. This option can be customized on a major-mode basis, i.e. if a `major-mode' is contained in this option then all tags for this modes will be initially expanded - otherwise not. - User Option: non-semantic-parsing-function Define mode-dependent parsing functions for non-semantic files. This is an alist where the car is a major-mode symbol and the cdr is a function-symbol of a function which should be used for parsing a non-semantic buffer, i.h. a buffer for which no semantic grammar exists. Such a function gets one argument - the filename of current buffer - and has to generate and return a tag/tag list which is understandable by `speedbar-insert-generic-list'. speedbar has already included two functions `speedbar-fetch-dynamic-imenu' and `speedbar-fetch-dynamic-etags' which can be used for parsing buffers with imenu rsp. etags. This option takes only effect if `ecb-process-non-semantic-files' is not nil: Then ECB checks for non-semantic buffers if current `major-mode' is contained in this option and if yes, then the specified parsing function is called; if not then the cars of the elements of `speedbar-dynamic-tags-function-list' are called in that sequence they are listed in this variable. See option `speedbar-dynamic-tags-function-list' for further details. In most cases imenu-parsing is preferable over etags-parsing because imenu operates on Emacs-buffers and needs no external tool and therefore parsing works also if current contents of a buffer are not saved to disk. But maybe sometimes etags may return better parsing results IMPORTANT: if imenu-parsing should be used then the option `speedbar-use-imenu-flag' must be set to not nil! - User Option: process-non-semantic-files Display content of non-semantic-files in the ECB-methods-buffer. See also `ecb-non-semantic-parsing-function'. - User Option: rebuild-non-semantic-methods-before-hook Hook running at beginning of the function `ecb-rebuild-methods-buffer-for-non-semantic'. This function is always called by the command `ecb-rebuild-methods-buffer' for not semantic supported source-types. Every function of this hook gets one argument: The complete filename of the current source-buffer in the edit-window. The Method-buffer is only rebuild by `ecb-rebuild-methods-buffer-for-non-semantic' if either the hook contains no function (the default) or if no function of this hook returns nil! See `run-hook-with-args-until-failure' for description how these function are processed.  File: ecb.info, Node: ecb-winman, Next: ecb-mode-line, Prev: ecb-non-semantic, Up: Customizable options Group ecb-winman ---------------- This group contains settings for supporting several window-managers: - User Option: winman-escreen-number Number of the escreen which is reserved for ECB. If you go to the escreen with this number you go always to the escreen with activated ECB. All other escreen-numbers are escreens with deactivated ECB! - User Option: winman-winring-name Name of the winring-window-configuration reserved for ECB. If you go to the window-configuration with this name you go always to the window-configuration with activated ECB. All other window-configuration are configurations with deactivated ECB!  File: ecb.info, Node: ecb-mode-line, Next: ecb-version-control, Prev: ecb-winman, Up: Customizable options Group ecb-mode-line ------------------- This group contains settings for the modelines of the ECB-tree-buffers: - User Option: mode-line-data Data shown in the modelines of the special ECB-buffers. Everey element of this list is a cons-cell where the car is used to define a buffer-name and the cdr to define the modeline-data for that buffer. For details about how to defining a buffer-name see `ecb-mode-line-prefixes' - its completely the same. The cdr is the data for ths modeline and can either be the symbol `sel-dir' or `sel-source' whereas the former one displays the current selected directory as modeline-data and the latter one the current selected source-file (without path). In addition to these two predefined values for every special ECB-buffer a plain string (which is displayed) or a function can be specified which gets three args (name of the buffer, current selected directory and current selected source-file) and must return a string which will be displayed in the modeline (or nil if no data should be displayed). Such a function can add the text-property `help-echo' to the result-string. Then this help-string will be displayed when the user moves the mouse over this section of the modeline. If a special ECB-buffer should not display special data in its modeline then this buffer-name should either not being added to this option or added with "No data" (= nil as cdr). The whole modeline of the special ECB-buffer consists of the prefix of `ecb-mode-line-prefixes' and the data of `ecb-mode-line-data' - eventually prepended by the window-number, see `ecb-mode-line-display-window-number'. - User Option: mode-line-data-face Face used for the data in the mode-line. See `ecb-mode-line-data'. For XEmacs the face should inherit from the face `modeline' (see `set-face-parent')! - User Option: mode-line-display-window-number Display in the modeline of every special ECB-window the window-number. The left-top-most window in a frame has the window-number 0 and all other windows are numbered with increasing numbers in the sequence, functions like `other-window' or `next-window' would walk through the frame. This can be used to jump to windows by number with commands like: (defun my-switch-to-window-number (number) ``Switch to the nth window'' (interactive ``P'') (if (integerp number) (select-window (nth number (window-list))))) Currently this feature is only available for GNU Emacs 21.X, because neither GNU Emacs < 21 nor XEmacs can evaluate dynamically forms in the mode-line. - User Option: mode-line-prefixes Prefixes shown in the modelines of the special ECB-buffers. The displayed prefix then looks like: "[ [: ]]", means if a prefix is defined for an special ECB-buffer then a single space is prepended and if there is additional text to display (e.g. the current directory in the sources buffer, see `ecb-mode-line-data') then also the string ": " is appended. Everey element of this list is a cons-cell where the car is used to define a buffer-name and the cdr to define the modeline-prefix for that buffer. The buffer-name can either be defined as plain string or with a symbol which contains the buffer-name as value. The latter one is recommended to define a prefix for one of the builtin ECB-tree-buffers because then simply the related option-symbol can be used. To add a prefix for the builtin directories tree-buffer just set the symbol `ecb-directories-buffer-name' as car. The cdr is the prefix for a buffer and can either be a string which used as it is or a function-symbol which is called with three argument (the buffer-name, the current selected directory and the current selected source-file) and must return either nil (for no prefix) or a string which is then used a prefix. Such a function can add the text-property `help-echo' to the result-string. Then this help-string will be displayed when the user moves the mouse over this section of the modeline. If a special ECB-buffer should not have a prefix in its modeline then this buffer-name should either not being added to this option or added with "No prefix" (= nil as cdr). - User Option: mode-line-prefix-face Face used for the prefix in the mode-line. See `ecb-mode-line-prefixes'. For XEmacs the face should inherit from the face `modeline' (see `set-face-parent')! - User Option: mode-line-win-nr-face Face used for the window-number in the mode-line. See `ecb-mode-line-display-window-number'. For XEmacs the face should inherit from the face `modeline' (see `set-face-parent')!  File: ecb.info, Node: ecb-version-control, Prev: ecb-mode-line, Up: Customizable options Group ecb-version-control ------------------------- This group contains settings for the version-control-support of ECB: - User Option: vc-directory-exclude-regexps Which directories should be excluded from VC-state-check. If a directory matches any of the regexps of this option the VC-state of its sources will not be checked - This option takes only effect if `ecb-vc-enable-support' is not nil. - User Option: vc-enable-support Enable support for version-control (VC) systems. If on then in the directories-buffer (if the value of the option `ecb-show-sources-in-directories-buffer' is on for current layout), the sources-buffer and the history-buffer all file-items are displayed with an appropriate icon in front of the item-name to indicate the VC-state of this item. If off then no version-control-state checking is done. Because this check can be take some time if files are managed by a not local Version-control-server ECB performs this check stealthy (see `ecb-stealthy-tasks-delay') so normally there should no performance-decrease or additional waiting-time for the user. But to get sure this option offers three choices: `t', `unless-remote' and `nil'. See the option `ecb-prescan-directories-for-emptyness' for an explanation for these three choices. The option `ecb-vc-directory-exclude-regexps' offers are more fine granularity to exclude the sources of certain directories from the VC-state-check. See `ecb-vc-supported-backends' and `ecb-vc-state-mapping' how to customize the VC-support itself. - User Option: vc-state-mapping Mapping between VC-states from the backends and ECB-known VC-states. ECB understands the following state-values: `up-to-date' The working file is unmodified with respect to the latest version on the current branch, and not locked. `edited' The working file has been edited by the user. If locking is used for the file, this state means that the current version is locked by the calling user. `needs-patch' The file has not been edited by the user, but there is a more recent version on the current branch stored in the master file. `needs-merge' The file has been edited by the user, and there is also a more recent version on the current branch stored in the master file. This state can only occur if locking is not used for the file. `added' The working file has already been added/registered to the VC-system but not yet commited. `unlocked-changes' The current version of the working file is not locked, but the working file has been changed with respect to that version. This state can only occur for files with locking; it represents an erroneous condition that should be resolved by the user. `ignored' The version-control-system ignores this file (e.g. because included in a .cvsignore-file in case of CVS). `unknown' The state of the file can not be retrieved; probably the file is not under a version-control-system. All state-values a check-vc-state-function of `ecb-vc-supported-backends' can return must have a mapping to one of the ECB-state-values listed above. If for a certain backend-VC-state no mapping can be found then per default 'edited is assumed! The default value of this option maps already the possible returned state-values of `vc-state' and `vc-recompute-state' (both GNU Emacs) and `vc-cvs-status' (Xemacs) to the ECB-VC-state-values. - User Option: vc-supported-backends Define how to to identify the VC-backend and how to check the state. The value of this option is a list containing cons-cells where the car is a function which is called to identify the VC-backend for a DIRECTORY and the cdr is a function which is called to check the VC-state of the FILEs contained in DIRECTORY. Identify-backend-function: It gets a full directory-name as argument - always without ending slash (rsp. backslash for native Windows-XEmacs) - and has to return a unique symbol for the VC-backend which manages that directory (e.g. 'CVS for the CVS-system or 'RCS for the RCS-system) or nil if the file is not managed by a version-control-system. Check-vc-state-function: It gets a full filename (ie. incl. the complete directory-part) and has to return a symbol which indicates the VC-state of that file. The possible returned values of such a check-vc-state-function have to be mapped with `ecb-vc-state-mapping' to the allowed ECB-VC-state values. ECB runs for a certain DIRECTORY all identify-backend-functions in that order they are listed in this option. For the first which returns a value unequal nil the associated check-state-function is used to retrieve the VC-state of all sourcefiles in that DIRECTORY. There is no need for the identify-backend-function or the check-vc-state-function to cache any state because ECB automatically caches internally all necessary informations for directories and files for best possible performance. To prepend ECB from checking the VC-state for any file set `ecb-vc-enable-support' to nil. Default value for GNU Emacs: Support for CVS, RCS, SCCS and Subversion (for the later one the most recent version of the VC-package incl. the vc-svn library is needed) is added per default. To identify the VC-backend the functions `ecb-vc-managed-by-CVS', `ecb-vc-managed-by-RCS' rsp. `ecb-vc-managed-by-SCCS' rsp. `ecb-vc-managed-by-SVN' are used. For all three backends the function `ecb-vc-state' of the VC-package is used. Default value for XEmacs: XEmacs contains only a quite outdated VC-package, especially there is no backend-independent check-vc-state-function available (like `vc-state' for GNU Emacs). Only for CVS a check-vc-state-function is available: `vc-cvs-status'. Therefore ECB adds per default only support for CVS and uses `ecb-vc-managed-by-CVS' rsp. `vc-cvs-status'. Example for GNU Emacs: If `vc-recompute-state' (to get real state-values not only heuristic ones) should be used to check the state for CVS-managed files and `vc-state' for all other backends then an element (ecb-vc-dir-managed-by-CVS . vc-recompute-state) should be added at the beginning of this option. - User Option: vc-xemacs-exclude-remote-cvs-repository Exclude directories with a remote cvs-repository from VC-check. This option takes only effect for XEmacs and is needed cause of the outdated VC-package of XEmacs which offers no heuristic state-checking and also no option `vc-cvs-stay-local'. So this option takes only effect if `vc-cvs-stay-local' is not avaiable. In this case ECB treats directories which are managed by CVS but have a remote repository as if the directory would be not managed by CVS (so the files are not checked for their VC-state). This si done to avoid blocking XEmacs when running full cvs-commands (e.g. "cvs status") over the net. Note: When ECB can find the option `vc-cvs-stay-local' then this option will automatically take no effect regardless which Emacs-version is used.  File: ecb.info, Node: Submitting problem report, Next: Upgrading, Prev: Customizing, Up: Top Submitting a problem report *************************** If you run into problems with ECB you should first take a look into - *Note FAQ:: or - *Note Conflicts and bugs:: or - *Note Tips and tricks:: or - the appropriate section of this online-manual. If your problem(s) still remain you can/should send a problem report to the ECB mailing list . ECB offers you a command which does all necessary for you to send a problem report. Just call `ecb-submit-problem-report'! Please read the documentation of this command, see *Note Interactive ECB commands::. *IMPORTANT*: Cause of extra appearance of SPAM in the mailing-lists, SourceForge has changed its policy: Now it is only possible to post to the mailing-list for users who have subscribed this mailing-list. So please be aware you will not be able to send comments, bug reports and improvement suggestions before you have subscribed the ECB-mailing-list. See the section "Mailing-list" at the ECB-website at how to do this. If you think there are problems concerning parsing-results for certain sources supported by semantic then you should call `ecb-dump-semantic-toplevel' for the problematic source-buffer *BEFORE* you call `ecb-submit-problem-report' because this "dump"-command generates for the current-buffer a new buffer with name "*ecb-tag-dump*" which contains all semantic-tags for this source. The contents of this "*ecb-tag-dump*" will then autom. be added to the problem-report generated by `ecb-submit-problem-report'! This command creates a problem-report buffer for you. After that you get a menu "Mail" (dependent on the mail-package used, the menu can have a different name) with commands to send the problem report. But for this the variable `mail-user-agent' must be configured right for your system. If you canīt get working this mechanism you can simply copy the whole problem-report buffer after filling it out and sending it with your standard mail-client to ! Please read also the documentation of the option `ecb-debug-mode' and switch on the debug mode of ECB (also available in the Help-menu of ECB!) before submitting a problem-report!  File: ecb.info, Node: Upgrading, Next: Tips and tricks, Prev: Submitting problem report, Up: Top Upgrading and downloading packages ********************************** This chapter describes all aspects of upgrading to a newer version of ECB. The first section describes how to download and install a new package from the web, where "package" means either ECB itself or the required libraries semantic, eieio and speedbar. After installing a new ECB-version ECB checks if the values of the customized ECB-options are still compatible. If not ECB does some smart things. This is the topic of the second section. * Menu: * Downloading new versions:: How to download newer versions of packages * Auto. option-upgrading:: ECB can auto. upgrade your options  File: ecb.info, Node: Downloading new versions, Next: Auto. option-upgrading, Prev: Upgrading, Up: Upgrading Downloading new versions of ECB and/or required packages ======================================================== ECB offers the possibility to upgrade to newer versions direct from the ECB-website. This can be done if the following requirements are satisfied: 1. A connection to the web is available 2. The tools "wget", "tar" and "gzip" are installed With Unix-systems these tools are in the standard-distribution. If you are running any Microsoft Windows system then you need cygwin(1) which offers these tools too. On every system these tools must reside in the `PATH' environment-variable! If you are behind a firewall and you have to use a proxy you maybe need the following wget-configuration in your file `~/.wgetrc': # Define your proxies (where 8080 and 8081 are examples # for the port-numbers) http_proxy = http://your.proxy.com:8080 ftp_proxy = http://your.ftpproxy.com:8081 # If you do not want to use proxy at all, set this to off. use_proxy = on If these requirements are satisfied you can download and install both ECB itself and also the required versions of semantic, eieio and speedbar: * Download a new ECB-version with `ecb-download-ecb': A description for this command you will find in *Note Interactive ECB commands::. Check also the options of the customize-group 'ecb-download' (*note ecb-download::). * Download and install of required packages: ECB checks at load-time if the packages semantic, eieio and speedbar are at least installed and at start-time if the required versions of semantic, eieio and speedbar (see `README') are installed and loaded into Emacs. If not you will be asked if you want auto. download and install them. If you confirm this then ECB does the following: 1. Checking which versions are available at the download-site of the required packages. With the option `ecb-download-package-version-type' you can specify which type of versions (only stable, stable and betas or stable, betas and alphas) you allow to download and install. This option offers also the choice of asking you for a certain version. Depending on this setting ECB either ask you which version it should download and install or chooses autom. the newest version available which is matching both its min-max-requirements and the setting in `ecb-download-package-version-type'. NOTE: Currently there are only beta-versions of speedbar available therefore this option has to be set to 1 (allow stable and beta versions). But the speedbar beta-versions are very stable! 2. Downloading and installing the right version (see 1.) of the required packages. ECB downloads and installs the new package versions in subdirectories of `ecb-download-install-parent-dir'. If both of these actions succeed then you will get a message-buffer which tells you something like: ----------------------------------------------------------------- Current state of the required packages semantic, eieio, speedbar: - semantic author-version must be [1.4, 1.4.9]: Installed in /usr/local/lib/site-lisp/semantic-1.4 - eieio author-version must be [0.17, 0.17.9]: Correct version already loaded! - speedbar author-version must be [0.14beta1, 0.15.9]: Correct version already loaded! After adding the new directory to your `load-path' and then restarting Emacs the new package(s) can be activated. ----------------------------------------------------------------- *Remark 1*: "P author-version must be [x y]" means, that ECB requires package P in a version-number >= x and <= y. *Remark 2*: By setting the option `ecb-version-check' to `nil' you can prevent ECB from checking correct versions of semantic, eieio and speedbar but it's strongly recommended not to do this! ---------- Footnotes ---------- (1) cygwin is available at  File: ecb.info, Node: Auto. option-upgrading, Prev: Downloading new versions, Up: Upgrading Automatic upgrading of options ============================== * Menu: * User interface:: Options and commands you should know * Background information:: Maybe some interesting informations  File: ecb.info, Node: User interface, Next: Background information, Prev: Auto. option-upgrading, Up: Auto. option-upgrading User interface for option-upgrading ----------------------------------- There are two interactive commands (*note Interactive ECB commands::): - `ecb-upgrade-options': Does all necessary beginning with a incompatibility-check for all options, upgrading/resetting incompatible options and ending with the display of all upgraded or reset options. - `ecb-display-upgraded-options': Displays an information-buffer which options have been upgraded or reset. Offers two buttons where the user can decide if the upgraded options should also being saved by ECB for future settings or if the buffer should be killed. If the option `ecb-auto-compatibility-check' has a non-nil value (which is the default) then ECB does all this stuff automatically at startup. This is very recommended! If you are interested in some background information, read *Note Background information::!  File: ecb.info, Node: Background information, Prev: User interface, Up: Auto. option-upgrading Background information ---------------------- Big packages like ECB will be enhanced and developed continuously so sometimes a new version must be released. Such packages offer in general a lot of customizable options so probably some of these options change the type or are renamed because the old type and/or name of the option makes no sense in the new release. Especially options which have changed the type of their value are now a problem for the user which want to upgrade to the latest ECB-version: If the user has saved a certain value for option X in its file `.emacs' but the type of this saved value doesn't match the new defined type in the defcustom-form after an ECB-upgrade then there can occur serious problems like ECB can not be started anymore or even Emacs can not be started without errors. Until now there was only one way to fix these problems: The user must manually edit his file `.emacs' and remove all entries for options which have now another type. After this and after restarting Emacs the new default-values of the type-changed options in the new ECB-release are active and the user can go on using Emacs and ECB. But this approach to fix the incompatible-option-problem has two serious drawbacks: 1. The user must manually edit the customize-section in his file `.emacs'. This should normally not be done and if then only by old-handed Emacs-users. 2. The customized value of the option X in the old-release (with the old type) is lost because after removing the related entry from the file `.emacs' the new default-value is active, so the user must re-customize the option X. OK, this is one half of the option-upgrade-problem but a new ECB-release can also rename a option from name X to name Y because the new name Y makes much more sense and/or is more mnemonic. If only the name has changed but not the type this is not a serious problem like above but also annoying because the customized value of the old-option X takes no effect in the new release but instead the default-value of the new-option Y is now active. But nevertheless this problem has the drawback number 2 (see above). The last category of upgrade-problems is a renamed option which has also changed its type. ECB has a solution for all these problems: * It checks all customized values of all ECB-options if they are still type-compatible. If not then it tries to upgrade the old-value to the new value-type and if this is not possible then it resets the option to the new default value and offers then to store it via customize in the .emacs-file (or in any file which is used for customized options). But ECB does not touch any customization-file without asking the user! * It offers a special constant `ecb-upgradable-option-alist' which allows the ECB-maintainers to define special transformings for renamed options so even the value of an old-option X can be savely transformed to the new-option Y and the old setting is not lost. All these checks and transformings are done at beginning of activating ECB - if the option `ecb-auto-compatibility-check' is not nil. If ECB has recognized incompatible or renamed options it does its upgrading/reseting-job so all ECB-options have correct types so ECB can start correct. After ECB is started it displays a list of all upgraded or reseted option with their old and new values.  File: ecb.info, Node: Tips and tricks, Next: Elisp programming, Prev: Upgrading, Up: Top Tips and tricks *************** This chapter contains some tips and tricks how to deal best with some situations. * Menu: * Changing faces:: Changing faces in the ECB tree-buffers * Small screens:: Working with small screens * Big screens:: Working with big screens * Simulating speedbar:: Simulating speedbar without an extra frame * Integrating speedbar:: Integrating speedbar in the ECB-frame * Large directories:: Working with large directories * Remote directories:: Working with remote directories * Version-control support:: Supporting Version control systems * Using eshell:: Optimal using of eshell in ECB * Grepping directories:: Grepping directories with ECB * Working with JDEE:: Working best with ECB and JDEE * Compile-window on demand:: Displaying the compile-window on demand * Non-semantic sources:: Parsing and displaying non-semantic sources * Hide-show:: Using hide-show from the methods-buffer-menu * Window-managers and ECB:: Support of several Emacs-window-managers * Using semanticdb:: Using semanticdb for going to external nodes  File: ecb.info, Node: Changing faces, Next: Small screens, Prev: Tips and tricks, Up: Tips and tricks Changing faces in the ECB tree-buffers ====================================== There are two basic faces: * `ecb-default-general-face': Basic face for displaying an ECB-tree-buffer. Itīs recommended to define the font-family, the font-size, the basic color etc. with this face. In GNU Emacs 21.X all faces (even the face `ecb-default-highlight-face') used in the ECB tree-buffers inherit from this face. Therefore the default attributes like font etc. of a face used in a tree-buffer can be very easily changed with face `ecb-default-general-face'. With XEmacs there is no inheritance-feature but the options `ecb-directories-general-face', `ecb-sources-general-face', `ecb-methods-general-face' and `ecb-history-general-face' offer the choice to use the face `ecb-default-general-face' so also with XEmacs the basic face-settings can be easily changed just by customizing the face `ecb-default-general-face'. * `ecb-default-highlight-face': Basic face for highlighting the current node in an ECB-tree-buffer. In GNU Emacs 21.X all highlighting faces used in the ECB tree-buffers inherit from this face. Therefore the default attributes like font etc. of a highlighting face used in a tree-buffer can be very easily changed with face `ecb-default-highlight-face'. With XEmacs there is no inheritance-feature but the options `ecb-directory-face', `ecb-source-face', `ecb-method-face' and `ecb-history-face' offer the choice to use the face `ecb-default-highlight-face' so also with XEmacs the basic face-settings can be easily changed just by customizing the face `ecb-default-highlight-face'. With these faces you can change the basic attributes easily and fast for ALL ECB-tree-buffers. But you are also able to display each ECB-tree-buffer with different faces, see the different options for every tree-buffer mentioned above. *Please note* (only for XEmacs users): Cause of the lack of the font-inheritance feature using ONE other font for the ECB-methods buffer can NOT be achieved just by setting `ecb-methods-general-face' to `ecb-default-general-face' and changing the font of this default face. In addition you have to set the same font also for the face `ecb-bucket-node-face' like in the following example: (defconst my-ecb-font "-outline-Courier-normal-normal-13-97-96-96-c-*-iso8859-1") (set-face-font 'ecb-default-general-face my-ecb-font) (set-face-font 'ecb-bucket-node-face my-ecb-font) This code sets the new defined font `my-ecb-font' as font for all(1) ECB-tree-buffers (incl. the methods buffer). ---------- Footnotes ---------- (1) Of course `ecb-directories-general-face', `ecb-sources-general-face', `ecb-methods-general-face' and `ecb-history-general-face' must be set to `ecb-default-general-face'!  File: ecb.info, Node: Small screens, Next: Big screens, Prev: Changing faces, Up: Tips and tricks Working with small screens ========================== If your screen is very small so you need every square-centimeter for displaying the buffer which you want to edit, ECB offers you a special layouts, where only the ECB-methods buffer is displayed on top or on left-side. Here comes what you should/can do to work best with ECB in such a situation: * First customize your ECB: 1. Customize `ecb-layout-name' to layout-name "top2" (on top) or "left9" (on left-side) 2. Ensure that `ecb-compile-window-height' is nil. 3. Optional: Adjust the `ecb-windows-height' rsp. `ecb-windows-width'. 4. Save your changes. * To edit your buffers: Call `ecb-toggle-ecb-windows' (also available via the menu "ECB" and by `C-c . lw') or `ecb-hide-ecb-windows' to hide the ECB-method buffer so you get all the place of your screen for editing. * To browse and select functions: Call `ecb-toggle-ecb-windows' or `ecb-show-ecb-windows' to make the ECB-method buffer visible if not already. If you want select a method/variable with the keyboard instead with the mouse you should read the section *Note Using the keyboard:: in this online help! The possibility of hiding temporally the ECB windows like described above is also useful for all the other layouts.  File: ecb.info, Node: Big screens, Next: Simulating speedbar, Prev: Small screens, Up: Tips and tricks Working with big screens ======================== ECB offers a layout type "left-right" with special ECB-tree-windows on the left and right side of the edit-area. The layouts "leftright1" and "leftright2"are examples for this layout type. See *Note Creating a new ECB-layout:: and *Note The layout-engine:: for details about how to create or program more layouts of this type. Such a layout is eventually the best choice for big screens because the several ECB-tree-windows are bigger and can display more informations without scrolling. With such a layout it can could be senseful to reduce the value of the option `ecb-windows-width' compared to layouts of type left or right. A value of max. 0.25 should be enough.  File: ecb.info, Node: Simulating speedbar, Next: Integrating speedbar, Prev: Big screens, Up: Tips and tricks Simulating speedbar without an extra frame ========================================== You can simulate a speedbar-like layout within ONE frame by doing the following: 1. Customize `ecb-layout-name' to layout name "left9", "left12", "left13" or "left14" dependent to what you like. 2. Optional: Ensure that `ecb-compile-window-height' is nil. 3. Optional: Adjust the `ecb-windows-width'. 4. Optional: Customize `ecb-toggle-layout-sequence' and toggle very fast between several layouts by `ecb-toggle-layout'. See the doc-strings! 5. Optional: Customize `ecb-show-sources-in-directories-buffer' to not nil if the chosen layout (see 1. and 4.) contains a directories-tree-buffer. 6. Save your changes. But not only simulating speedbar is possible but also full integrating it into the ECB and the ECB-frame, *Note Integrating speedbar::.  File: ecb.info, Node: Integrating speedbar, Next: Large directories, Prev: Simulating speedbar, Up: Tips and tricks Integrating speedbar in the ECB-frame ===================================== It is very easy to integrate speedbar into ECB. There are two different ways to do this: 1. You can either use speedbar in the directories-, sources- or methods-window of ECB instead of the built-in directory-, sources- or methods-browser of ECB. This can be done via the option `ecb-use-speedbar-instead-native-tree-buffer'. 2. Or you can integrate an extra speedbar-window into a layout independent of the existence of a directory-, sources- or methods-window. For this you can either use the built-in layout "left-dir-plus-speedbar" or you have to create your own layout interactively with the command `ecb-create-new-layout'. This way is not described in more details because there is nothing more to describe - just create your layout. In general integrating speedbar into the ECB-frame makes sense for people... * ...who like the speedbar way of handling directories and source-files but also like the ECB-way of displaying the buffer-contents (like methods and variables in a source-file). This people should use the option `ecb-use-speedbar-instead-native-tree-buffer' and set it to `dir'. * ...who like the speedbar way of browsing things like directories, files, file-contents etc. but who dislike the extra speedbar-frame. Note: It is not necessary to integrate speedbar if you only want parsing sources not supported by semantic. From version 1.94 on ECB supports native parsing and displaying of such sources (*note Non-semantic sources::)! Regardless the group you belong, with the speedbar-integration feature of ECB you can combine both worlds, the speedbar- and the ECB-world: 1. Choose a layout which either contains a directories- or a sources-window but not both of them(1). Because speedbar has also display-modes for buffers and info-nodes and some other useful things (which can be changed by the speedbar-command `speedbar-change-initial-expansion-list' we recommend layouts like "left15" or "leftright3" for using with speedbar. 2. Set the option `ecb-use-speedbar-instead-native-tree-buffer' to not nil. After this the chosen window of ECB will contain a full featured speedbar (the only difference to standard speedbar is not residing in an extra frame). Note: If you belong to the first group of people (s.a.) a similar effect and usability is available by setting `ecb-use-speedbar-instead-native-tree-buffer' to nil and setting `ecb-show-sources-in-directories-buffer' to not nil, because this combination displays also directories and sources in one window. So with the option `ecb-use-speedbar-instead-native-tree-buffer' you have the choice which way of displaying and handling "things" (directories, sources, methods...) you want (the speedbar- or the ECB-way). During speedbar is running within ECB (i.e. `ecb-use-speedbar-instead-native-tree-buffer' is not nil) the speedbar-command `speedbar' is disabled and the speedbar-command `speedbar-get-focus' switches between the speedbar-window and the edit-window(2). *IMPORTANT*: ECB can only integrate speedbar-versions >= 0.14beta1! If you use lower versions of speedbar `ecb-use-speedbar-instead-native-tree-buffer' has no effect. ---------- Footnotes ---------- (1) Only one of them is needed if you use speedbar because speedbar displays directories and sources in one window. But if you like wasting space then you can also use a layout with both windows... (2) The standard behavior is switching between the speedbar-frame and the attached frame, but this make obviously no sense during running speedbar with ECB.  File: ecb.info, Node: Large directories, Next: Remote directories, Prev: Integrating speedbar, Up: Tips and tricks Working with large directories ============================== If `ecb-source-path' contains directories with many files and subdirs, especially if these directories are mounted net-drives ("many" means here something > 500, dependent on the speed of the net-connection and the machine), actualizing the sources- and/or directories- buffer of ECB (if displayed in current layout!) can slow down dramatically. If this is a problem the contents of certain directories and also the contents of the sources-buffer can be cached which increases the speed a lot. See the option `ecb-cache-directory-contents'. IMPORTANT: The full speed-advantage of this cache-mechanism is only available if `ecb-show-sources-in-directories-buffer' is `nil', i.e. sources of a directory are displayed in the ECB-sources-window. The reason is that only with a sources window the tree-buffer contents for the sources can be cached (i.e. the buffer-content of the ECB-sources-window) whereas with sources displayed in the directories buffer only the disk-contents of a directory are cached - which increases speed too but not so much as with sources displayed in the extra window ECB-sources. The cache of a directory can be only refreshed by a POWER-click (with mouse or keyboard) onto the related directory-node in the directories-buffer of ECB (*note Using the mouse::). See also the option `ecb-cache-directory-contents-not'. Here are some useful settings for both of these options: * Cache all directories with more than 500 entries: Set `ecb-cache-directory-contents' to ((".*" . 500)) and set `ecb-cache-directory-contents-not' to nil. * Cache only all directories > 200 beginning with /usr/ Set `ecb-cache-directory-contents' to (("^/usr/.*" . 200)) and set `ecb-cache-directory-contents-not' to nil. * Cache all directories > 500 but NOT these beginning with /usr/: Set `ecb-cache-directory-contents' to ((".*" . 500)) and set `ecb-cache-directory-contents-not' to ("^/usr/.*"). Another way for getting a faster overlook for large directories with many source-entries is to apply an online-filter to the sources-buffer. This can be done via the command `ecb-sources-filter' or via the popup-menu of the sources-buffer.  File: ecb.info, Node: Remote directories, Next: Version-control support, Prev: Large directories, Up: Tips and tricks Working with remote directories =============================== The term "remote" means directories which are remote in the sense of TRAMP(1), ANGE-FTP(2) or EFS(3). Each of these Emacs-addons is intended to make editing directories and files on remote machines as transparent as possible. General remarks --------------- ECB supports such remote directoires out of the box and completely transparently, i.e. you can add remote directories to the option `ecb-source-path' without any restriction. ECB will handle these directories transparently with the appropriate tool - either TRAMP, ANGE-FTP or EFS. So when working with such a remote directory is possible without ECB it will be possible too with active ECB - at least as long you are "connected"! *Caution*: Suppose you have added a remote dir (e.g. "user@host.at.a.server:/dir/") to `ecb-source-path' and you start ECB when you are offline, means there can be no connection established to the remote computer (e.g. "host.at.a.server"). Each time ECB has to process a remote path ECB pings via the ping-program the remote host (in the example above it would ping the host "host.at.a.server") to test if it is accessible. If not then this path will be ignored by ECB(4). Ensure that ECB calls your ping-program (see `ecb-ping-program') with the right options (see `ecb-ping-options'). To avoid to many pings to the same host ECB caches the ping result so there should be no performance decrease. But to ensure still correct accessible-results and to avoid using outdated cache-results ECB discards the cached value of the accessible-state of a certain host after a customizable time-interval (please read the documentation of `ecb-host-accessible-check-valid-time'!). Excluding remote directories from time-consuming tasks ------------------------------------------------------ ECB performs some tasks stealthily and interruptable by the user (see the option `ecb-stealthy-tasks-delay' for additional explanations) because these tasks are time-consuming and could otherwise ECB block. Especially for remote directories these special tasks can cause annoying blocks of Emacs (*note Stealthy background tasks::). Therefore it is probably the best to switch on each of the stealthy tasks with the `unless-remote' which is the default activation (*note Stealthy background tasks::). So a certain stealthy task will be swtiched on for all local directories (and also for all mounted drives in the LAN) but not for real remote directories used via TRAMP, ANGE-FTP or EFS. Caching the contents of remote directories ------------------------------------------ ECB caches per default the contents of remote directories to avoid annoying delays. The cache is done via the option `ecb-cache-directory-contents' which contains an entry which covers the syntax of remote directories. If you do not want this caching (which is strongly recommened) you have to remove this entry from this option. ---------- Footnotes ---------- (1) TRAMP stands for 'Transparent Remote (file) Access, Multiple Protocol'. This package provides remote file editing, similar to ANGE-FTP. (2) This package attempts to make accessing files and directories using FTP from within Emacs as simple and transparent as possible. (3) A system for transparent file-transfer between remote hosts using the FTP protocol within Emacs (4) This avoids long lasting and annoying blocking of ECB when a remote-path is not accessible: Without a ping ECB would always try to open this directory through the appropriate library (e.g. TRAMP) and it would depend on the timeout-mechanism of this library (e.g. TRAMP has 60 seconds) how long ECB would be blocked. First after this timeout ECB could start working! A fast "pre"-ping avoids this problem!