..                            -*- rst-mode -*-
.. Copyright (c) 2004 Guenter Milde and the Debian Jed Group
   Released under the terms of the GNU General Public License (v. 2 or later)


Organizing jed-extra
====================

When designing jed-extra, let us follow

"Goccia's Rules of Thumb":
~~~~~~~~~~~~~~~~~~~~~~~~~~

   1. it should be as helpful as possible; but 
   2. it must not stand in the way; therefore, 
   3. it should be fully customisable, and 
   4. it should be usable by geeks and newbies alike.

   -- Guido Gonzato

The jed-extra package should therefore

a) "just work" once it is installed,
b) not impose settings on the user that cannot be reverted.

As this is somewhat contradictory, a "low level" activation in
/etc/jed.d/50jed-extra.sl seems to be most suited. 
(See `Possible Levels of Support`_ support below for a more detailled
discussion.)


Download URL
------------

In order to be included, a package|mode needs a "canonical site" from which
it can be fetched non-interactively. 

Unfortunately, the standard URL for a Sourceforge release cannot serve as
such a canonical site, as it requires user interaction to select a mirror.
Therefore alternatively a fixed mirror URL for a Jedmodes-CVS release or a
URL for a pre-release source archive on the Jedmodes home site is used.


Categorization
--------------

Instead of a direct copy of Jedmodes-CVS, jed-extra should install an
"intelligent" choice of packages: purge obsolete packages and add
interesting new ones. As Jedmodes is a heterogeneous collection of
user-provided modes, some categorization/sorting seems in place.


Considering the interference with JED, 4 types of modes can be distinguished
(cf. the list in "contents.txt"):

A: Additions
~~~~~~~~~~~~

* add a new capability but keep the "look and feel"

* add 1 or 2 autoloads but nothing "heavy"

* example: language modes like make.sl

-> install in the libdir and activate by default


D: Drop-in replacements
~~~~~~~~~~~~~~~~~~~~~~~

* provide an "improved" look and feel (enhance usability)

* might slow down startup, increase memory or CPU usage

* do not need activation

* example: help.sl (hyperhelp), man.sl (hyperman), recent.sl

-> install in libdir/drop-in *added* in the config file 
   ( cf. `Where should the modes go?`_)


E: Enhancements
~~~~~~~~~~~~~~~

* provide an "improved" look and feel or enhance usability

* medium interference: add to popup menus or keybindings 
  (other than _Reserved_Key_Prefix)

* might slow down startup, increase memory or CPU usage

* example: numbuf.sl, navigate.sl

-> install in the libdir but activation should be configurable: 
comments in 50jed-extra.sl and doc/jed-extra/examples/jed.rc 
   

O: Obsoleted modes
~~~~~~~~~~~~~~~~~~

* unmaintained and obsoleted modes that are still in Jedmodes for
  historical reasons
  
-> do not install  
  

U: Utils
~~~~~~~~

* example: bufutils.sl

* provide functions used by other modes

-> install in libdir/utils
no need for activation (calling mode should have autoload() or require())


X: eXperimental and eXotic modes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* some modes are in a rather experimental, untested state or just need some
  work to become up to date.

* other modes are of limited interest (exotic user cases)
  
-> install in libdir/extra but do not activate


Where should the modes go?
--------------------------

* The `jed-extra library directory` is ``/usr/share/jed/jed-extra/``
  
  The `jed-extra library directory` should be appended to the search
  path (with append_libdir() from libdir.sl in jed.d/50jed-extra.sl).
  This way the performance impact on searches in the libdir or
  documentation is kept minimal.

* Some modes are drop-in replacements. Placing them in the
  jed_library_path would either
   
  a) make their use obligatory for all users if the libdir is *added* 
     (i.e. prepended), or
  b) prevent their use if the libdir is *appended*.

  Drop-ins should therefore go to ``/usr/share/jed/jed-extra/drop-in/``,
  added to the library path in 50jed-extra.sl.
  
  * The default behaviour would be to use the drop-ins if jed-extra
    is installed.
  * A sysadmin can easily comment out the activation of drop-ins
  * A user can remove the drop-in/ dir from the library path in jed.rc
    (a function remove_libdir() in libdir.sl could assist)  
  * Fine-grained activation of drop-ins is possible by copying or symlinking
    of individual modes to a users (or local) libdir.


Possible Levels of Support
--------------------------


1. Provide the modes sorted like the upstream,
   installation should be "by hand" (in /usr/local/...  or ~/.jed/lib/).
   
   - no added value (why then a package at all?)
   
2. Provide modes and a framework for installation 
   (e.g. add /usr/local/jed/site-lib/ to the search path
   in /etc/jed.d/50jed-extra.sl using add_libdir() from libdir.sl)
   
   + facilitates "hand-installation"
   + allows "fine tuning" by experts
   
   - hard for novices
   - Installing jed-extra will not (automatically) improve the 
     usability of JED.

3. Install a choice of modes (inclusive adding autoloads and
   add_completion())
     
   a) choosen by the packagers
   
      + simple, no questions at install time
      
      - Violates Goccia's Rule 2. (could stand in the way).
   
   b) choosen from a list with debconf
   
      + Allows administrators to change choice easily with dpkg-reconfigure.
      
      - debconf abuse (violates Debian policy)
      
   c) choosen from a list in a jed-extra-installer.sl mode
   
      as this is no system configuration, it must not change anything
      under /usr/share/jed/ or /usr/share/jed/jed-extra/.
      
      + user friendly
      
      - lots of work (wont be finished soon)
      
   d) "minimal-invasive" activation in jed.d/
   
      * Categorize modes regarding their "invasiveness" (see Categorization_)
      * Activate "non obstructing" modes in jed.d/50jed-extra.sl
      * Add comments for activating the other categories
      * Describe the activation/configuration in README.debian
      * Provide an example jed.rc for user configuration
      
      + 50jed-extra.sl is a config file, so the admin can override our
        choice.
      + Prepared configuration options for categories make configuration
        a bit more user friendly
        
      - no GUI
          

