This is ecb.info, produced by makeinfo version 4.3 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-layout,  Next: ecb-face-options,  Prev: ecb-history,  Up: Customizable options

Group ecb-layout
----------------

This group contains the following options:

 - User Option: ecb-activate-before-new-frame-created-hook
   Normal hook run before the new ECB-frame is created if
   `ecb-new-ecb-frame' is not nil (otherwise this hook is not
   evaluated).

 - User Option: ecb-advice-window-functions
   Use the intelligent windows functions of ECB instead of the standard
   Emacs functions. You can choose the following functions to be adviced
   by ECB so they behave as if the edit-window(s) of ECB would be the
   only windows(s) of the ECB-frame:

    * `other-window' For this one see also the option
      `ecb-other-window-jump-behavior'!

    * `delete-window'

    * `delete-other-windows'

    * `delete-windows-on'

    * `split-window-horizontally'

    * `split-window-vertically'

    * `switch-to-buffer'

    * `switch-to-buffer-other-window'

    * `other-window-for-scrolling' If this advice is enabled then the
      following functions scroll always the first edit-window if the
      edit-window is splitted, point stays in the "other" edit-window
      and there is no durable compilation-window (see
      `ecb-compile-window-height'):

       - `scroll-other-window'

       - `scroll-other-window-down'

       - `beginning-of-buffer-other-window'

       - `end-of-buffer-other-window'

      This advice is per default not enabled.

   For working most conveniantly with ECB it is the best to advice all
   these functions, because then all the standard shortcuts of these
   functions are also usable with ECB without doing anything else. Also
   other packages can interact best with ECB if these functions are all
   adviced. If these adviced functions are called in another frame than
   the ECB-frame they behave all exactly like the not adviced versions!

   But please read also the following:

   Normally all packages should work correct with ECB and itīs adviced
   functions but if there occur problems with a package cause of some of
   these adviced functions ECB offers the following fall-back solution:

   1. Deactivate in `ecb-advice-window-functions' all the
      adviced-functions which make problems with other packages.

   2. For every of the adviceable functions <adv-func> ECB offers a
      interactively function named "ecb-<adv-func>" which does exactly
      the same as the adviced version of <adv-func>. Use
      "ecb-<adv-func>" instead the original one to get the proper ECB
      behavior even if the function is not adviced anymore.

   3. You can bind in `ecb-activate-hook' the standard-shortcut of
      <adv-func> to "ecb-<adv-func>" and rebind it in
      `ecb-deactivate-hook' to <adv-func>.

   4. Now you have the best of both worlds: The problematic package
      works and you have the ECB-behavior of <adv-func> as if it would
      be adviced.

   Here is an example: Suppose you must deactivating the advice for
   `switch-to-buffer-other-window'. Then you deactivate this function
   with this option and you can use `ecb-switch-to-buffer-other-window'
   instead. Bind the shortcut you normally use for
   `switch-to-buffer-other-window' to
   `ecb-switch-to-buffer-other-window' (use `ecb-activate-hook' for
   this) and rebind it to the original function in the
   `ecb-deactivate-hook'.

 - User Option: ecb-compile-window-enlarge-by-select
   The compile-window is auto. enlarged after selecting it. If not nil
   then selecting the `ecb-compile-window' auto. enlarges it and
   deselecting (means selecting another window after point was in
   `ecb-compile-window') auto. shrinks it. Enlarging and shrinking the
   `ecb-compile-window' is done with
   `ecb-toggle-enlarged-compilation-window'. See also the documentation
   of this function!

 - User Option: ecb-compile-window-height
   If you want a compilation window shown at the bottom of the
   ECB-layout then set here the height of it (Default is a height of
   5). If you redraw the current layout with `ecb-redraw-layout' then
   the compilation window (if any) has the heigth you set here. If the
   number is less than 1.0 the height is a fraction of the frame height.

   If you do not set a durable compilation window then doing a
   compilation splits temporally the edit window vertically if the edit
   window is not splitted already or uses the "other" edit window
   temporally for comilation output if the edit window is already
   splitted. This is the recommended value for this option!

   Beware: If you set a durable compilation window then ECB can not
   guarantee always behaving like a standard Emacs concerning displaying
   temp-buffers and compilation-buffers. It should work in most cases
   but maybe not in all. Just try it out.

   See also the option `ecb-compile-window-temporally-enlarge' and also
   the function `ecb-toggle-enlarged-compilation-window'!

   *Note Temp- and compile-buffers::.

   Regardless of the settings you define here: If you have destroyed or
   changed the ECB-screen-layout by any action you can always go back to
   this layout with `ecb-redraw-layout'

 - User Option: ecb-compile-window-temporally-enlarge
   Let Emacs temporally enlarge the compile-window of the ECB-layout.

   This option has only an effect if `ecb-compile-window-height' is not
   nil!

   The following values are possible:

    - `after-compilation': After finishing the compilation-output and
      during jumping to the errors ECB let temporally enlarge all
      compilation-buffers in `ecb-compile-window' (e.g. compile- and
      grep-buffers) to `compilation-window-height'. But be aware this
      setting is currently not meaningful for temporary buffers like
      help-buffers because these buffers currently enlarge always to
      `temp-buffer-max-height'.

    - `after-selection': Selecting the `ecb-compile-window' auto.
      enlarges it and deselecting (means leaving `ecb-compile-window')
      auto. shrinks it. Enlarging and shrinking the
      `ecb-compile-window' is done with
      `ecb-toggle-enlarged-compilation-window'. See also the
      documentation of this function! This is possible for all buffers
      in `ecb-compile-window' not only for compilation-buffers!

    - `both': The combination of 'after-compilation and
      'after-selection.

    - `nil': ECB tries to fix always the height of the
      `ecb-compile-window' at the value of `ecb-compile-window-height'.
      But for all temporary buffers (e.g. help-buffers) this is
      currently not possible.

   To restore the ECB-layout after such a buffer-enlarge just call
   `ecb-toggle-enlarged-compilation-window' or `ecb-redraw-layout'.

 - User Option: ecb-hide-ecb-windows-hook
   Hooks run after the ECB windows have been hidden either by
   `ecb-toggle-ecb-windows' or `ecb-hide-ecb-windows'.

 - User Option: ecb-layout-always-operate-in-edit-window
   Adviced window functions work always in the edit-window. If we are in
   an ECB special buffer (methods, directories, etc), and any of the
   adviced windowing functions is called (see
   `ecb-advice-window-functions'), we will select the `ecb-edit-window'
   first. This is useful if you have any functions that use such
   functions and you don't want them to just error with a method
   complaining that the current buffer can not be split, or something
   similar.

   Because this may not be desirable in all situations and all adviced
   functions this can be enabled separately for every advisable function
   (see also `ecb-advice-window-functions'). If the symbol of an
   adviced function is contained in the value of this option, then the
   edit-window is first selected otherwise either an error is reported
   or some other special reaction; see the documentation of the adviced
   functions for this.

   For `other-window' and `other-window-for-scrolling' this makes no
   sense, therefore you can not enable this for both of them.

   Per default this is enabled for `delete-window',
   `delete-other-windows', `switch-to-buffer' and
   `switch-to-buffer-other-window'.

 - User Option: ecb-layout-nr
   Define the window layout of ECB. A positive integer which sets the
   general layout. Currently there are 17 predefined layouts with index
   from 0 to 16. You can savely try out any of them by changing this
   value and saving it only for the current session. If you are sure
   which layout you want you can save it for future sessions. To get a
   picture of the layout for index <index> call C-h f
   ecb-layout-function-<index>, e.g.  `ecb-layout-function-9'.

   Currently available layouts (see the doc-string for a picture ot the
   layout):

   `ecb-layout-function-0' `ecb-layout-function-1'
   `ecb-layout-function-2' `ecb-layout-function-3'
   `ecb-layout-function-4' `ecb-layout-function-5'
   `ecb-layout-function-6' `ecb-layout-function-7'
   `ecb-layout-function-8' `ecb-layout-function-9'
   `ecb-layout-function-10' `ecb-layout-function-11'
   `ecb-layout-function-12' `ecb-layout-function-13'
   `ecb-layout-function-14' `ecb-layout-function-15'
   `ecb-layout-function-16'

   Regardless of the settings you define here: If you have destroyed or
   changed the ECB-screen-layout by any action you can always go back to
   this layout with `ecb-redraw-layout'

 - User Option: ecb-layout-switch-to-compilation-window
   Switch-to-buffer...-functions switch to `ecb-compile-window'. If the
   buffer argument of `switch-to-buffer' or
   `switch-to-buffer-other-window' is an compilation buffer as defined
   with `ecb-compilation-buffer-p' we will select the
   `ecb-compile-window' first. This is useful if you always want your
   compilation buffers within the compilation window and now within the
   edit window.

   Note the difference between
   `ecb-layout-always-operate-in-edit-window' and this option: If a
   switch-to-buffer...-function is contained in the former one, then we
   always jump first into the edit-window regardless of the destination
   buffer. If also contained in this option then ECB checks the
   destination buffer and then selects the `ecb-compile-window' if it
   is a compilation-buffer in the meaning of `ecb-compilation-buffer-p'!

   Per default this is only enabled for `switch-to-buffer'. We provide
   the option for `switch-to-buffer-other-window' too but the
   assumption is that when a user asks for a buffer in another window
   it should always be presented in another window.

 - User Option: ecb-layout-window-sizes
   Specifies the sizes of the ECB windows for each layout. The easiest
   way to change this variable is to change the window sizes by dragging
   the window borders using the mouse and then store the window sizes by
   calling the `ecb-store-window-sizes' function. Next time the layout
   is redrawn the values stored in this option will be used.

   But be aware: These values are only suitable for the frame-size the
   ecb-frame had at the time you store the values by calling
   `ecb-store-window-sizes'. Therefore ensure always before calling
   `ecb-store-window-sizes' that the ecb-frame has the size it has
   normally during your work with ECB!.

 - User Option: ecb-new-ecb-frame
   Create a new frame at activation time of ECB.

 - User Option: ecb-other-window-jump-behavior
   Which windows of ECB should be accessible by the ECB-adviced function
   `other-window', an intelligent replacement for the Emacs standard
   version of `other-window'. The following settings are possible:

    - `all': ECB will cycle through all windows of ECB, means it
      behaves like the original `other-window'.

    - `only-edit': ECB will only cycle through the (max. 2)
      edit-windows of ECB.

    - `edit-and-compile': Like 'only-edit plus the compile window if
      any.

 - User Option: ecb-redraw-layout-quickly
   If non-nil, we will attempt to redraw the layout quickly. Please read
   also carefully the documentation of `ecb-redraw-layout'.

 - User Option: ecb-select-edit-window-on-redraw
   Select the first edit window on `ecb-redraw-layout'.

 - User Option: ecb-show-ecb-windows-hook
   Hooks run after the ECB windows have been shown either by
   `ecb-toggle-ecb-windows' or `ecb-show-ecb-windows'.

 - User Option: ecb-split-edit-window
   Sets how and if the edit window should be splitted. But be aware:
   This option determines only if the edit-window should be splitted at
   start-time of ECB.

 - User Option: ecb-toggle-layout-sequence
   Toggle sequence for layout toggling with `ecb-toggle-layout'.  Every
   element of this list has to be a valid layout-number (see option
   `ecb-layout-nr').

   You can add here as many layouts as you want but to use this option
   most effective you should not add more than 2 or 3 layouts so every
   layout can be accessed very fast by toggling with
   `ecb-toggle-layout'. It is also senseful to add layouts which have
   the same principal outline, i.e. all their tree-buffers are on the
   same side of the frame and the tree-buffer-"column" (or -"row") has
   identical size for the layouts.

   Recommended values are for example:

    - (11 16), toggles between methods and directories/history

    - (11 15), toggles between methods and directories

    - (11 14), toggles between methods and history

    - (11 14 15), toggles between methods, history and directories

   This option makes only sense if the value is a list with more than 1
   element!

 - User Option: ecb-windows-height
   The height of the ECB windows in lines when they are placed above or
   below the edit window. If the number is less than 1.0 the width is a
   fraction of the frame height.

 - User Option: ecb-windows-width
   The width of the ECB windows in columns when they are placed to the
   left or right of the edit window. If the number is less than 1.0 the
   width is a fraction of the frame width.


File: ecb.info,  Node: ecb-face-options,  Next: ecb-faces,  Prev: ecb-layout,  Up: Customizable options

Group ecb-face-options
----------------------

This group contains the following options:

 - User Option: ecb-directories-general-face
   Basic face for the ECB directories buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

 - User Option: ecb-directory-face
   Define face used for highlighting current directory in the
   directories buffer.

 - User Option: ecb-history-face
   Define face used for highlighting current history-entry in the
   history buffer.

 - User Option: ecb-history-general-face
   Basic face for the ECB history buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

 - User Option: ecb-method-face
   Define face used for highlighting current method, class or variable
   in the methods buffer.

 - User Option: ecb-methods-general-face
   Basic face for the ECB methods buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

 - User Option: ecb-source-face
   Define face used for highlighting current source in the sources
   buffer.

 - User Option: ecb-source-in-directories-buffer-face
   Define a face for displaying sources in the directories buffer.

 - User Option: ecb-sources-general-face
   Basic face for the ECB sources buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

 - User Option: ecb-token-header-face
   Define face used for highlighting the token header after jumping to
   it by clicking onto a node in the methods buffer.


File: ecb.info,  Node: ecb-faces,  Next: ecb-download,  Prev: ecb-face-options,  Up: Customizable options

Group ecb-faces
---------------

This group contains the following faces:

`ecb-bucket-token-face:'
   Face which can be used for displaying bucket tokens in the methods
   buffer. See also `ecb-bucket-token-display'.

`ecb-default-general-face:'
   Basic face for all ECB tree-buffers.  It's recommended to define
   here the font-family, the font-size, the basic color etc.

   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 and GNU Emacs 20.X 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 and GNU Emacs 20.X
   the basic face-settings can be easily changed just by customizing the
   face `ecb-default-general-face'!

`ecb-default-highlight-face:'
   Define basic face for highlighting the selected node in an ECB
   tree-buffer.

   In GNU Emacs 21.X all highlighting faces in the ECB tree-buffers
   inherit from this face. Therefore the default attributes like font
   etc. of a face used in a tree-buffer for highlighting the current
   token can be very easily changed with face
   `ecb-default-highlight-face'.

   With XEmacs and GNU Emacs 20.X 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 and GNU Emacs
   20.X the basic face-settings can be easily changed just by
   customizing the face `ecb-default-highlight-face'!

`ecb-directories-general-face:'
   Basic face for the ECB directories buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

`ecb-directory-face:'
   Define face used for highlighting current directory in the
   directories buffer.

`ecb-history-face:'
   Define face used for highlighting current history-entry in the
   history buffer.

`ecb-history-general-face:'
   Basic face for the ECB history buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

`ecb-method-face:'
   Define face used for highlighting current method, class or variable
   in the methods buffer.

`ecb-methods-general-face:'
   Basic face for the ECB methods buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

`ecb-source-face:'
   Define face used for highlighting current source in the sources
   buffer.

`ecb-source-in-directories-buffer-face:'
   Define a face for displaying sources in the directories buffer.

`ecb-sources-general-face:'
   Basic face for the ECB sources buffer. Itīs recommended to define
   here the font-family, the font-size, the basic color etc.

`ecb-token-header-face:'
   Define face used for highlighting the token header after jumping to
   it by clicking onto a node in the methods buffer.

`ecb-type-token-class-face:'
   Define face used with option `ecb-type-token-display'.

`ecb-type-token-enum-face:'
   Define face used with option `ecb-type-token-display'.

`ecb-type-token-group-face:'
   Define face used with option `ecb-type-token-display'.

`ecb-type-token-interface-face:'
   Define face used with option `ecb-type-token-display'.

`ecb-type-token-struct-face:'
   Define face used with option `ecb-type-token-display'.

`ecb-type-token-typedef-face:'
   Define face used with option `ecb-type-token-display'.

Just call `customize-face <face-name>' to customize these faces for
your personal taste. Or customize the related option in the group *Note
ecb-face-options::.


File: ecb.info,  Node: ecb-download,  Next: ecb-help,  Prev: ecb-faces,  Up: Customizable options

Group ecb-download
------------------

This group contains the following options:

 - User Option: ecb-download-delete-archive
   Should the downloaded archive be deleted after successfull
   installation or after failure during the installation-process.
   Possible values are:

    - `only-after-success': Archive is only deleted after successfull
      installation but not if a failure occurs during the installation
      process.

    - `always': Archive is also deleted if an error occurs.

    - `nil': Archive will never be deleted.

 - User Option: ecb-download-url
   URL where downloadable ECB-versions are located. The ECB-archive-file
   (e.g. ecb-1.70.tar.gz) will be appended to this URL and
   `ecb-download-ecb' will try to download this archive.

   Note: Normally this URL should never change but who knows...

 - User Option: ecb-download-version
   Which version of ECB should be downloaded by `ecb-download-ecb'.
   Valid values are either the string "latest" or a version number like
   "1.70". ECB creates automatically the correct URL for download, see
   `ecb-download-ecb' (*note Interactive ECB commands::).


File: ecb.info,  Node: ecb-help,  Prev: ecb-download,  Up: Customizable options

Group ecb-help
--------------

This group contains the following options:

 - User Option: ecb-help-html-path
   Path where the ECB online help in HTML format resides. This must be
   the location of the file `ecb.html' which comes with the ECB
   distribution. If is installed by unpacking the archive available on
   the ECB website then this is the installation directory of ECB, i.e.
   where the elisp files of ECB reside. If it is installed as
   XEmacs-package (e.g. via the package manager of XEmacs) then this is
   probably not the directory where the elisp files of ECB reside but
   either the directory "../../html/" or "../../etc/ecb/html/" (both
   relativ to the elisp directory of ECB).

   The path can either be an absolute path or a path relativ to the
   directory where the elisp files of ECB are.

   Normally there should be no need to change this option!

 - User Option: ecb-help-info-path
   Path where the ECB online help in info format resides. This must be
   the location of the file `ecb.info' which comes with the ECB
   distribution. If is installed by unpacking the archive available on
   the ECB website then this is the installation directory of ECB, i.e.
   where the elisp files of ECB reside. If it is installed as
   XEmacs-package (e.g. via the package manager of XEmacs) then this is
   probably not the directory where the elisp files of ECB reside but
   the directory "../../info/" (relativ to the elisp directory of ECB).

   The path can either be an absolute path or a path relativ to the
   directory where the elisp files of ECB are.

   Normally there should be no need to change this option!

 - User Option: ecb-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.


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 can/should send a problem report
to the ECB mailing list <ecb-list@lists.sourceforge.net>. 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, *Note Interactive ECB commands::.

This command creates a problem-report buffer for you. After that you
get a menu "Mail" (dependend on the mail-package used, the menu can
have a different name) with commands to send the problem report. But
for this the varibale `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 <ecb-list@lists.sourceforge.net>!

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 and eieio.

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 portnumbers)
      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 and eieio:

 * 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::).

   ECB will try to download the file:

      <URL><PACKAGE>-<VERSION>.tar.gz

   where

  `URL'
      Value of the option `ecb-download-url'.

  `PACKAGE'
      The string "ecb"

  `VERSION'
      Value of the option `ecb-download-version'.

 * Download and install of required packages:

   ECB checks at start-time if the required author-versions of semantic
   and eieio (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 and the download and install succeeds then you will
   get a message-buffer which tells you something like:

      ---------------------------------------------------------------
      Current state of the required packages semantic and eieio:
      
      - Required version of semantic (author version): 1.4:
        Installed in /usr/local/lib/site-lisp/semantic-1.4
      
      - Required version of eieio (author version): 0.17:
        Correct version already loaded!
      
      After adding the new directory to your `load-path' and then
      restarting Emacs the new package(s) can be activated.
      ---------------------------------------------------------------

   *Note*: By setting the option `ecb-version-check' to `nil' you can
   prevent ECB from checking correct versions of semantic and eieio,
   but it's strongly recommended not to do this!


---------- Footnotes ----------

(1) cygwin is available at <http://cygwin.com/>


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 a temp. buffer with all
   upgraded or resetted ECB-options with their old and new values.

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 continously 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
startet 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-optons 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 store it via customize in the
   .emacs-file (or in any file which is used for customized options).

 * 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 resetted 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
* Simulating speedbar::         Simulating speedbar without an extra frame
* Integrating speedbar::        Integrating speedbar in the ECB-frame
* Optimize scrolling::          Optimize scrolling in the edit-window
* Large directories::           Working with large directories
* Using eshell::                Optimal using of eshell in ECB


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.

 * `ecb-default-highlight-face': Basic face for highlighting the
   current node in an ECB-tree-buffer.

With this 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. For further details see the
doc-strings of the faces `ecb-default-general-face' and
`ecb-default-highlight-face' (just call `customize-face' to see the
doc-strings). The options of the group 'ecb-face-options' are also
interesting.


File: ecb.info,  Node: Small screens,  Next: Simulating speedbar,  Prev: Changing faces,  Up: Tips and tricks

Working with small screens
==========================

If your screen is very small so you need every sqare-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-nr' to layout nr. 10 (on top) or nr. 11 (on
      left-side)

   2. Ensure that `ecb-compile-window-height' is nil.

   3. Optional: Ajust the `ecb-windows-height' resp.
      `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 . w') 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: Simulating speedbar,  Next: Integrating speedbar,  Prev: Small 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-nr' to layout nr. 11, 14, 15 or 16 dependend to
   what you like.

2. Optional: Ensure that `ecb-compile-window-height' is nil.

3. Optional: Ajust 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 choosen layout (see 1. and 4.) contains a
   directories-tree-buffer.

6. Save your changes.


File: ecb.info,  Node: Integrating speedbar,  Next: Optimize scrolling,  Prev: Simulating speedbar,  Up: Tips and tricks

Integrating speedbar in the ECB-frame
=====================================

This feature will be first available in future versions of ECB.


File: ecb.info,  Node: Optimize scrolling,  Next: Large directories,  Prev: Integrating speedbar,  Up: Tips and tricks

Optimize scrolling in the edit-window
=====================================

Emacs 20.X seems to slow down scrolling if there is a horizontal split
in the frame and/or a lot of overlays in the buffer which is scrolled.
This is independend of ECB! But because almost all layouts of ECB uses
horizontal splits of the frame and because ECB is based on semantic
which uses overlays intensively there can be poor scrolling performance
in large buffers, especially with java-buffers in `jde-mode'.

This scrolling performance can be increased a lot if the options
`scroll-conservatively' and `scroll-step' are set appropriatelly: The
former one should have a value of 0 during ECB is active and the latter
one a value of either 0 or > 1 (the exact value depends on the power of
your machine).

As far as we know this is not a problem of Emacs 21.X or XEmacs. With
these versions of Emacs there should be no scrolling problem even with
`scroll-step' has value 1.


File: ecb.info,  Node: Large directories,  Next: Using eshell,  Prev: Optimize scrolling,  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 > 1000, dependend 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 can be cached
which increases the speed a lot. See `ecb-cache-directory-contents'.


File: ecb.info,  Node: Using eshell,  Prev: Large directories,  Up: Tips and tricks

Optimal using of eshell in ECB
==============================

Documentation currently not available.


File: ecb.info,  Node: Elisp programming,  Next: Conflicts and bugs,  Prev: Tips and tricks,  Up: Top

Entry points for elisp programmers
**********************************

This chapter describes how ECB can be used/programmed/driven by an
elisp-program. This contains:

* Menu:

* List of variables::           Which variables an elisp-program can use
* List of hooks::               All available hooks
* tree-buffer::                 Some words to the tree-buffer-library
* Adviced functions::           How to deal with the adviced functions
* New layouts::                 How to program new layouts


File: ecb.info,  Node: List of variables,  Next: List of hooks,  Prev: Elisp programming,  Up: Elisp programming

Variables for elisp-programs
============================

Variables an elisp-program can use:

 * `ecb-source-path-functions'

Look at the documentation of these variables to get a description.


File: ecb.info,  Node: List of hooks,  Next: tree-buffer,  Prev: List of variables,  Up: Elisp programming

Available hooks of ECB
======================

The following hooks are available:

 * `ecb-activate-before-new-frame-created-hook'

 * `ecb-activate-before-layout-draw-hook'

 * `ecb-activate-hook'

 * `ecb-deactivate-hook'

 * `ecb-show-ecb-windows-hook'

 * `ecb-hide-ecb-windows-hook'

 * `ecb-current-buffer-sync-hook'

Look at the documentation of these hooks to get a description.


File: ecb.info,  Node: tree-buffer,  Next: Adviced functions,  Prev: List of hooks,  Up: Elisp programming

The library tree-buffer.el
==========================

The library tree-buffer.el is ECB independent and can be used for other
applications too. But such an application is not allowed to use any of
the variables of tree-buffer.el especially not the variable
*tree-buffers*!

`tree-buffers': Only for internal use. It contains all tree-buffers of
current Emacs-instance, means *all* tree-buffers of *all* applications
which uses currently tree-buffers. Every application must store its own
collection of tree-buffers in an own variable! For example: ECB stores
its tree-buffer set in `ecb-tree-buffers'!

An application may only use the methods tree-buffer.el provides but no
internal variables!


File: ecb.info,  Node: Adviced functions,  Next: New layouts,  Prev: tree-buffer,  Up: Elisp programming

How to deal with the adviced window-functions
=============================================

ECB offers for packages which work during activated ECB three macros
for easy temporally(1) using all original-functions, all adviced
functions or only some adviced functions:

 - `ecb-with-original-functions'

 - `ecb-with-adviced-functions'

 - `ecb-with-some-adviced-functions'

For a detailed explanation of each macro read the documentation with
`describe-function'!

---------- Footnotes ----------

(1) I.e. regardless of the settings in `ecb-advice-window-functions'!


File: ecb.info,  Node: New layouts,  Prev: Adviced functions,  Up: Elisp programming

How to program new layouts
==========================

Documentation will be added in future!


File: ecb.info,  Node: Conflicts and bugs,  Next: Command Index,  Prev: Elisp programming,  Up: Top

Known conflicts and bugs of ECB
*******************************

This chapter describes all already known conflicts with other packages
and also the known (and currently unfixed) bugs of ECB. If possible
then a practicable solution or workaround is described.

* Menu:

* Conflicts::                   Known conflicts with other packages
* Bugs::                        Known bugs


File: ecb.info,  Node: Conflicts,  Next: Bugs,  Prev: Conflicts and bugs,  Up: Conflicts and bugs

Known conflicts with other packages
===================================

Here is a list of known conflicts of ECB with other packages and
helpful solutions/hints/workarounds:

* Menu:

* VC::                          Conflicts with Version Control
* follow-mouse::                Conflicts with follow-mouse.el
* avoid::                       Conflicts with avoid.el
* calendar::                    Conflicts with calendar.el
* calculator::                  Conflicts with calculator.el


File: ecb.info,  Node: VC,  Next: follow-mouse,  Prev: Conflicts,  Up: Conflicts

Package VC (Version Control)
----------------------------

The variable `vc-delete-logbuf-window' must be set to nil during active
ECB. This can be done with the hooks mentioned in *Note Elisp
programming::.


File: ecb.info,  Node: follow-mouse,  Next: avoid,  Prev: VC,  Up: Conflicts

Package follow-mouse.el
-----------------------

The following is only relevant for Emacs 20.X!

ECB works very well with follow-mouse if follow-mouse is turned on
*BEFORE* ECB is activated (e.g. within the `ecb-activate-hook'). But if
you activate follow-mouse first after ECB is already activated, then
the follow-mouse stuff prevents the complete node-name to be displayed
in the echo-area if mouse moves over it. Because ECB has a much more
intelligent mouse tracking mechanism than follow-mouse the follow-mouse
stuff profit from ECB and works even better and saver as without
activated ECB!


File: ecb.info,  Node: avoid,  Next: calendar,  Prev: follow-mouse,  Up: Conflicts

Package avoid.el
----------------

With GNU Emacs 20.X ECB must deactivate `mouse-avoidance-mode' if the
option `ecb-show-node-info-in-minibuffer' activates for at least one
ECB tree-buffer 'if-too-long or 'always. This is done automatically but
only as long ECB is activated.


File: ecb.info,  Node: calendar,  Next: calculator,  Prev: avoid,  Up: Conflicts

Package calendar.el
-------------------

With activated ECB `calendar' does not shrink itīs window to the small
size but splits the window equally. But if you add this to your
`.emacs' it works:

   (add-hook 'initial-calendar-window-hook
             (function (lambda ()
                         (when (and ecb-minor-mode
                                    (ecb-point-in-edit-window))
                           ;; if no horizontal split then nothing
                           ;; special to do
                           (or (= (frame-width) (window-width))
                               (shrink-window (- (window-height) 9))))
                        )))


File: ecb.info,  Node: calculator,  Prev: calendar,  Up: Conflicts

Package calculator.el
---------------------

If the edit-window is already splitted then calling `calculator' uses
the whole "other" edit-window for the calculator. With an unsplitted
edit-window the calculator window has itīs normal size of about 2
lines. Therefore itīs recommended to set `calculator-electric-mode'
during ECB activation to not nil so calculator uses always the
echo-area instead of creating a new small window!


File: ecb.info,  Node: Bugs,  Prev: Conflicts,  Up: Conflicts and bugs

Known bugs
==========

This section describes all currently known bugs of ECB. The maintainers
of ECB try to fix these bugs as soon as possible.


File: ecb.info,  Node: Command Index,  Next: Option Index,  Prev: Conflicts and bugs,  Up: Top

Command Index
*************

This index contains all user commands of ECB:

* Menu:

* ecb-activate:                          Interactive ECB commands.
* ecb-add-all-buffers-to-history:        Interactive ECB commands.
* ecb-clear-history:                     Interactive ECB commands.
* ecb-current-buffer-sync:               Interactive ECB commands.
* ecb-cycle-through-compilation-buffers: Interactive ECB commands.
* ecb-deactivate:                        Interactive ECB commands.
* ecb-display-upgraded-options:          Interactive ECB commands.
* ecb-download-ecb:                      Interactive ECB commands.
* ecb-goto-window-compilation:           Interactive ECB commands.
* ecb-goto-window-directories:           Interactive ECB commands.
* ecb-goto-window-edit1:                 Interactive ECB commands.
* ecb-goto-window-edit2:                 Interactive ECB commands.
* ecb-goto-window-history:               Interactive ECB commands.
* ecb-goto-window-methods:               Interactive ECB commands.
* ecb-goto-window-sources:               Interactive ECB commands.
* ecb-minor-mode:                        Interactive ECB commands.
* ecb-nav-goto-next:                     Interactive ECB commands.
* ecb-nav-goto-previous:                 Interactive ECB commands.
* ecb-rebuild-methods-buffer:            Interactive ECB commands.
* ecb-redraw-layout:                     Interactive ECB commands.
* ecb-show-help:                         Interactive ECB commands.
* ecb-submit-problem-report:             Interactive ECB commands.
* ecb-toggle-ecb-windows:                Interactive ECB commands.
* ecb-toggle-enlarged-compilation-window: Interactive ECB commands.
* ecb-toggle-layout:                     Interactive ECB commands.
* ecb-update-directories-buffer:         Interactive ECB commands.
* ecb-upgrade-options:                   Interactive ECB commands.

