Metadata-Version: 1.1
Name: virtualenvwrapper-emacs-desktop
Version: 1.0
Summary: virtualenvwrapper plugin to control emacs desktop mode
Home-page: http://www.doughellmann.com/projects/virtualenvwrapper-emacs-desktop/
Author: Doug Hellmann
Author-email: doug.hellmann@gmail.com
License: UNKNOWN
Description: =================================================
         Using Emacs Desktop Mode with Virtualenvwrapper
        =================================================
        
        Emacs desktop-mode_ lets you save the state of emacs (open buffers,
        kill rings, buffer positions, etc.) between sessions.  It can also be
        used as a project file similar to other IDEs.  This virtualenvwrapper_
        plugin adds a trigger to save the current desktop file and load a new
        one when activating a new virtualenv using ``workon``.
        
        Installation
        ============
        
        Install this plugin with pip::
        
          $ pip install virtualenvwrapper-emacs-desktop
        
        Or by unpacking the source distribution and running ``setup.py`` directly::
        
          $ tar zxvf virtualenvwrapper-emacs-desktop-X.Y.tar.gz
          $ cd virtualenvwrapper-emacs-desktop-X.Y
          $ python setup.py install
        
        You may need administrator privileges to install to a global location.
        
        Configuring Desktop Mode in Emacs
        =================================
        
        Setup of desktop-mode is straightforward:
        
        1. Run ``customize-group`` on the "desktop" group.
        
        2. Turn ``desktop-save-mode`` **on** to enable the minor mode.
        
        3. Optionally change the base name for desktop files in
           ``desktop-base-file-name``. For example, using "emacs.desktop"
           means the file will not be hidden.
        
        4. Set a default search path for the desktop file in ``desktop-path``.
           Use your home directory, or the directory where you keep your emacs
           configuration files (``~/emacs.d`` or ``~/emacs``).  This value is
           the *default*.  Your real desktop files will be saved into the
           virtualenv directories.
        
        5. Set ``desktop-save`` to **Always save**. There are other values
           that work, but some require interaction with the editor during the
           context move to confirm file saves.
        
        There are a few other options that may be useful to tweak, depending
        on the other features of emacs you use. For example,
        ``desktop-clear-preserve-buffers`` lets you control which buffers are
        saved when the desktop is cleared on a reload.  It may be useful to
        save the ``*Messages*``, ``*Org Agenda*``, and ``*scratch*`` buffers,
        since those are related to emacs operation and not limited to any one
        project.
        
        Enabling the Plugin
        ===================
        
        Switching desktop sessions every time ``workon`` is used would make it
        impossible to have two shells open and working on separate projects at
        the same time.  Therefore, the plugin must be explicitly enabled in
        the shell where it should control the emacs session.
        
        Two shell functions (``emacs_desktop_controller_on`` and
        ``emacs_desktop_controller_off``) are provided to switch the plugin on
        and off.  They do this by changing the variable
        ``DESKTOP_CONTROLLER``, which the plugin examines before taking any
        action.  If the variable is not set, or is defined but empty, the
        plugin makes no changes.  If the variable is set to any value, the
        session is changed.
        
        Most modern terminal programs make it easy to create custom
        configurations with specific settings.  Use your terminal's
        customization feature to create a "desktop controller" configuration
        with ``DESKTOP_CONTROLLER`` set, then control
        virtualenvwrapper-emacs-desktop from a terminal using that
        configuration.
        
        Terminal.app
        ------------
        
        The default OS X terminal emulator Terminal.app lets you set up
        profiles with custom configurations, including running a command when
        the new window is opened.  Create a new profile, then under the
        **Shell** tab, set:
        
         :Run command: emacs_desktop_controller_on
         :Run inside shell: Enabled
        
        
        iTerm
        -----
        
        The third-party OS X terminal emulator iTerm_ lets you set up
        "bookmarks" with custom configurations, including the "Working Dir".
        One way to use this to control the plugin is to set up a special
        bookmark with a working directory set to ``$WORKON_HOME``, then add a
        check to ``~/.bashrc`` to check for that condition.
        
         :Name: emacs-control
         :Command: ``bash -l``
         :Working Dir: ``/Users/username/.virtualenvs``
         :Terminal: Default
         :Keyboard: Global
         :Display: Default
        
        ~/.bashrc settings::
        
            if [ "$(pwd)" = "$WORKON_HOME" ]
            then
                emacs_desktop_controller_on
            else
                emacs_desktop_controller_off
            fi
        
        .. _iTerm: http://iterm.sourceforge.net/
        
        emacs shell
        -----------
        
        shell-mode in emacs sets ``EMACS`` and ``INSIDE_EMACS``, so you can
        test for those environment variables.
        
        Gnome Terminal
        --------------
        
        ?
        
        KDE
        ---
        
        ?
        
        .. note::
        
           If you have suggested configuration mechanisms for other terminal
           emulators or other platforms, please post them in the comments and I
           will add them to this README file.
        
        References
        ==========
        
        * `Saving Emacs Sessions <http://www.gnu.org/software/emacs/manual/html_node/emacs/Saving-Emacs-Sessions.html>`__
        * `Desktop Save Mode <http://www.gnu.org/s/emacs/manual/html_node/elisp/Desktop-Save-Mode.html>`__
        * desktop-mode_
        * virtualenvwrapper_
        
        .. _desktop-mode: http://www.emacswiki.org/emacs/DeskTop
        
        .. _virtualenvwrapper: http://www.doughellmann.com/projects/virtualenvwrapper/
        
Platform: Any
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Requires: virtualenv
Requires: virtualenvwrapper (>=2.0)
Provides: virtualenvwrapper.emacs_desktop
