#!/bin/sh
# In short: this script invokes Emacs with eev-mode turned on.
# This file:             (find-eev "debian/emacs-eev")
#   http://angg.twu.net/eev-current/debian/emacs-eev.html
#   http://angg.twu.net/eev-current/debian/emacs-eev
# After installation it becomes:
#        (find-fline "/usr/bin/emacs-eev")
# Closely related:       (find-eev "debian/90eev.el")
#   http://angg.twu.net/eev-current/debian/90eev.el.html
#   http://angg.twu.net/eev-current/debian/90eev.el
# Author: Eduardo Ochs <eduardoochs@gmail.com>
# Version: 2010sep28
# Public domain.

# Invasiveness
# ============
# Eev-mode is invasive - it changes the actions of some keys that
# the Emacs manual says that minor modes should not touch...
#   See: (find-elnode "Keymaps and Minor Modes")
# Here is the description of eev-mode, from its docstring
# (extracted from the output of `(eek "M-h M-e")'):
#
#    The description of `M-x eev-mode' (from its docstring)
#    ------------------------------------------------------
#    Toggle eev mode, i.e, activate or deactivate the `eev-mode-map' keymap.
#    With a prefix argument ARG, turn eev-mode on if positive, else off.
#
#    Commands to follow hyperlinks:
#      M-E -- eval the sexp at the left of point
#      M-e -- go to the end of line, then do M-E
#    Commands to return from hyperlinks:
#      M-k -- kill this buffer
#      M-K -- put this buffer at the end of the list of all buffers
#    Commands to execute regions or steps:
#      <f3>  -- execute the default action on bounded regions
#      <f8>  -- pitch this line to another Emacs buffer,
#               or execute this line as lisp if it starts with `*'
#      <f9>  -- send this line through the default channel,
#               or execute this line as lisp if it starts with `*'
#      M-P   -- "send" the first line of the last kill, as if the
#               user had typed it
#      <f12> -- execute the next step from an `eesteps' list
#    Commands to convert the current line into hyperlinks:
#      M-F  -- wrap its contents in a `find-fline'
#      M-M  -- wrap its contents in a `find-man'
#      M-S  -- wrap its contents in a `find-sh'
#      M-T  -- generate an "* (eepitch-{xxx,kill,xxx})" block
#      M-C  -- wrap its contents in a `code-c-d' and a `find-_file'
#      M-D  -- wrap its contents in three Debian hyperlinks
#    Commands to generate pages with lists of hyperlinks:
#      M-h f   -- hyperlinks to the current file
#      M-h M-f -- hyperlinks to an Emacs function
#      M-h M-i -- hyperlinks to the current Info node
#      M-h M-k -- hyperlinks to a key sequence and to the function
#                 associated to it
#      M-h M-v -- hyperlinks to an Emacs variable
#      M-h M-s -- hyperlinks to a face (default: face at point)
#      M-h M-m -- hyperlinks to a manpage (ask for name)
#      M-h m   -- hyperlinks to a manpage (being viewed)
#      M-h M-d -- hyperlinks about a Debian package
#    Commands to edit hyperlinks:
#      M-h 2   -- duplicate this line
#      M-h M-y -- yank into pos-spec-list
#      M-I     -- transform filename into hyperlink
#    Other commands:
#      M-h M-e -- show this help about eev-mode, or some links
#      M-h M-c -- lots of info about the character at point
#      M-h M-t -- text properties at point
#      M-h t   -- text properties at point (output in the echo area)
#      M-?     -- switch to a help page, or hide it and return
#
#    Note: eev's hyperlinks behave so much more sensibly when
#    `pop-up-windows' is off that eev-mode sets that
#    variable (globally!) to nil when eev-mode is entered, and
#    restores the previous global value when you leave the mode. If
#    you don't like that behavior then do this (with eev-mode off):
#
#        (setq eev-mode-global-settings-saver nil)

# Solution
# ========
# This script provides an easy way to start Emacs with eev-mode turned
# on. The Debian package installs this script at /usr/bin/emacs-eev,
# and in most window managers you should be able to run it from a menu
# entry, that gets placed at:
#
#   Applications > Editors > Emacs+eev
#
# For the technical details of the menu entry see:
#   http://angg.twu.net/eev-current/debian/eev.menu.html
#    (find-angg        "eev-current/debian/eev.menu")
#
# The Emacs invoked by this script will usually even be _visually_
# different from the default one, due to these command-line options:
#
#   (find-enode "Colors" "-fg COLOR")
#   (find-enode "Colors" "-bg COLOR")
#
# Note that the command-line option `--funcall=eev-activate-initial'
# runs a function that is defined at:
#
#   http://angg.twu.net/eev-current/debian/90eev.el.html
#   http://angg.twu.net/eev-current/debian/90eev.el
#                 (find-eev        "debian/90eev.el")
#
# If you don't run it then the eev Debian package will not even add
# "/usr/share/emacs/site-lisp/eev" to your load-path - so this Debian
# package is much less invasive than most standard debianized Emacs
# add-ons!

# Beginners vs. advanced users
# ============================
# Advanced users should be interested in the "advanced installation",
# which is best done by running an e-script from inside Emacs.
# To open that e-script - in a buffer where you can run it
# step-by-step with `eepitch' - run this:
#
#   (find-eev-update-links)
#
# One of the intents of eev is to make Emacs much more accessible for
# beginners, and total beginners tend to find the standard ways to run
# that e-script quite difficult... they can just install the Debian
# package, then run "emacs-eev", then M-x find-eev-update-links.

exec emacs -fg bisque -bg black --funcall=eev-activate-initial $*

# See also:
#   (find-enode "Action Arguments" "`--funcall=FUNCTION'")
#   (find-status   "eev")
#   (find-vldifile "eev.list")
#   (find-udfile   "eev/")