[eev] "(require 'eev)" considered harmless

[Eduardo Nahum Ochs]

[The previous posting had a "cd" missing and spurious line breaks... again:]

Short version: if you're curious about eev but you don't want any
weird global side-effects, then you can do a "half-installation" of
eev with:

  mkdir ~/eev-current/                 ;# or any other dir
  cd    ~/eev-current/
  rm -v eev-current.tar.gz             ;# for wget
  wget http://angg.twu.net/eev-current.tar.gz
  tar -xvzf eev-current.tar.gz

  ;; The lines below are elisp, of course - use `M-x eval-region'
  (add-to-list 'load-path "~/eev-current")
  (load-library "eev.el")         ; (find-eev "eev.el")
  (load-library "eev-langs.el")   ; (find-eev "eev-langs.el")
  (load-library "eev-insert.el")  ; (find-eev "eev-insert.el")
  (load-library "eev-glyphs.el")  ; (find-eev "eev-glyphs.el")
  (load-library "eev-compose.el") ; (find-eev "eev-compose.el")

Then the elisp hyperlinks will all work, and you can use `M-x
eev-mode' to turn on and off eev's keybindings. If you don't turn on
eev-mode -- or if you turn it on and then turn it off -- then you'll
notice nothing.

Moral: download eev and install it.

Now the gory details.



--snip--snip--


"(require 'eev)" Considered Harmless -- Long Version
====================================================

Eev.el used to define eev-mode as a global minor mode that was on by
default. That meant that a person who wanted to try eev's hyperlink
functions would do "(require 'eev)", and then would end up with
several possibly annoying keybindings, like these:

  (define-key eev-mode-map "\M-E" 'eek-eval-last-sexp) ; extends     C-x C-e
  (define-key eev-mode-map "\M-e" 'eek-eval-sexp-eol)  ; extends C-e C-x C-e
  (define-key eev-mode-map "\M-k" 'kill-this-buffer)   ; convenience
  (define-key eev-mode-map "\M-K" 'bury-buffer)        ; convenience
  (define-key eev-mode-map [f3]   'eeb-default)
  (define-key eev-mode-map [f9]   'eechannel-do-this-line)
  (define-key eev-mode-map [f12]  'eesteps-do-step)

It was not hard to change that --- the `define-key's were all
grouped together in eev.el, there was an (if eev-mode-map () ...)
around the `define-key's for people who wanted to define their
own eev-mode-keymap, and eev-mode could be turned off --- but
that was not the right thing to do, and I'm afraid that that
behaviour could even have turned people away...

Also, eev's hyperlinks behave so much more sensibly when
pop-up-windows and debug-on-error (or eval-expression-debug-on-error)
are all turned off that at different times I have tried several
different strategies to convince people to turn these variables off
globally. At one time the "eev block" that the installer script adds
to the user's ".emacs" file contained `setq's that would set these
variables to nil; later that was changed to commented-out `setq's and
brief explanatory commands that I sincerely hoped that users would
read and understand...

Now all this has been fixed (I think). The code that goes into the
"eev block" of .emacs is now this:

  ;; Beginning of the eev block:
  ;; See: (find-eev "eev-rctool" "new_block_emacs")
  ;;
  (add-to-list 'load-path "~/eev-current")
  (load-library "eev.el")         ; (find-eev "eev.el")
  (eev-mode 1)                    ; (find-efunctiondescr 'eev-mode)
  (load-library "eev-langs.el")   ; (find-eev "eev-langs.el")
  (load-library "eev-insert.el")  ; (find-eev "eev-insert.el")
  (load-library "eev-glyphs.el")  ; (find-eev "eev-glyphs.el")
  (load-library "eev-compose.el") ; (find-eev "eev-compose.el")
  (ee-invade-global-namespace)    ; (find-eev "eev.el")
  (eev-set-default-glyphs)
  ;;
  ;; End of the eev block.

Now just loading eev.el should have no noticeable global effects. Some
functions and variables become defined (and all of them have prefixes
"find-" or "ee"), and some environment variables (all of them with
names starting with "EE") are set inside emacs, but nothing else. The
other four ".el" files are equally harmless.

The trick is that now turning on eev-mode takes care of both the
keymap and the global variables --- it activates eev-mode-map, and it
also keeps a backup of `pop-up-windows' and sets it to nil; turning
off eev-mode deactivates the keymap and restores the value of
pop-up-windows.

As for the other changes: `ee-invade-global-namespace' defines some
functions whose names don't start with "ee" or with "find-";
`eev-set-default-glyphs' makes "\^O"s display as red stars, "\^L"s as
a yellow "L"s on red backround, and a few other glyph changes.

The "full installation" of eev also defines `ee' as a shell function
in .bashrc and in .zshrc, as a function in .tclshrc and .gdbinit, and
prepares a directory (by default at ~/.eev/) -- where the functions of
eev that send blocks of commands to external programs (like eev and
eelatex) store these commands as temporary scripts.



A Half-Installation Is Much Better Than None
============================================

Surprise: incidentally, with (at least) a half-installation of eev it
becomes much easier to understand what the full installation does, and
also to go from "half-installed" to "fully-installed" -- or to upgrade
eev or to uninstall eev. Executing any of the `find-sh' sexps below
runs the argument as a shell command and displays the output in a
temporary buffer.

  * There's nothing to byte-compile, so "make" does nothing -- it just
    explains the next step.

      (find-sh "cd $EEVDIR; make")
      (find-eevfile "Makefile")
      (find-eevfile "INSTALL")

  * These sexps show what will be put in the "eev block" of your
    rcfiles.

      (find-sh "cd $EEVDIR; ./eev-rctool")
      (find-sh "cd $EEVDIR; ./eev-rctool new_block_emacs")
      (find-sh "cd $EEVDIR; ./eev-rctool new_block_bashrc")
      (find-sh "cd $EEVDIR; ./eev-rctool new_block_zshrc")
      (find-sh "cd $EEVDIR; ./eev-rctool new_block_tclshrc")
      (find-sh "cd $EEVDIR; ./eev-rctool new_block_gdbinit")

  * The first `find-sh' below creates a "~/.eev/" directory, which
    includes a "~/.eev/backup/" subdirectory with the changed rcfiles
    (they're not installed by default; to install them you need
    another command), plus backup rcfiles and scripts to install the
    new rcfiles and to revert the process.

    The process that creates the new rcfiles doesn't try to be very
    smart; if there's no "eev block" in the rcfile it is added to the
    end, which can be annoying when you have a "Local Variables:"
    section.

      (find-sh "cd $EEVDIR; ./eev-rctool prepare")
      (find-fline "~/.eev/backup/")
      (find-fline "~/.eev/backup/do_install.sh")
      (find-fline "~/.eev/backup/do_uninstall.sh")
      (find-sh "cd ~/.eev/backup/ && diff -u .emacs.backup   .emacs.new")
      (find-sh "cd ~/.eev/backup/ && diff -u .bashrc.backup  .bashrc.new")
      (find-sh "cd ~/.eev/backup/ && diff -u .zshrc.backup   .zshrc.new")
      (find-sh "cd ~/.eev/backup/ && diff -u .tclshrc.backup .tclshrc.new")
      (find-sh "cd ~/.eev/backup/ && diff -u .gdbinit.backup .gdbinit.new")
      (find-fline "~/.eev/backup/.emacs.new"   "Beginning of the eev block")
      (find-fline "~/.eev/backup/.bashrc.new"  "Beginning of the eev block")
      (find-fline "~/.eev/backup/.zshrc.new"   "Beginning of the eev block")
      (find-fline "~/.eev/backup/.tclshrc.new" "Beginning of the eev block")
      (find-fline "~/.eev/backup/.gdbinit.new" "Beginning of the eev block")

  * The `find-sh' below installs the ".new" rcfiles,

      (find-sh "cd $EEVDIR; ./eev-rctool install_rc")

  * And this one reverts it:

      (find-sh "cd $EEVDIR; ./eev-rctool uninstall_rc")

  * The "INSTALL" file shows the typical output of install_rc and
    uninstall_rc.

      (find-eevfile "INSTALL")
      (find-eevfile "INSTALL" "./eev-rctool install_rc")
      (find-eevfile "INSTALL" "./eev-rctool uninstall_rc")



Now Go On And Blah Blah Blah Bleh Bleh Bleh
===========================================

I hope that this will lower the entry bar for installing eev.el quite
a lot -- I would like to be at least able to paste eev sexps on the
#emacs IRC channel and not feel that I'm doing something
other-worldly.

(Eev is to be included in Emacs at some point; but I don't know how
close that is, and there are still a few changes that I want to do
before re-submitting a version of eev to the Emacs maintainers).

  Cheers,
    Eduardo Ochs
    http://angg.twu.net/
    edrx at mat.puc-rio.br
    "edrx" on the #emacs and #eev channels at irc.freenode.net