-*- outline -*-

This is a list of issues associated with upgrading the MH-E package in
XEmacs from 7.4.2 to 8.3.

* lots of changes

  The source tree has been reorganized, with the source code now
  living in a "lisp" subdirectory.  This requires changes in the
  top-level package repo (it knows which packages use a "lisp"
  subdirectory).

  I've tried to ensure that XEmacs-specific changes are not lost, but
  it's possible I missed something.

* incompatibilities with MH-E 7

  MH-E has a limited public API, so many packages use private
  functions/variables, or they have dependencies on the code
  structure, such as #'require a private feature or adding an autoload
  which may no longer point at the right file

    - The mh-loaddefs file contains the autoloads for the items tagged
      with ";;;###mh-autoloads". mh-e.el has (require 'mh-loaddefs).
      So other packages that do (require 'mh-e) and then invoke MH-E
      internal functions should be okay (assuming the function
      invocation is okay). It's other things, like variables, you
      still need to watch out for.

    - From Bill Wohler (upstream project lead): "only the functions in
      mh-autoloads.el are designed for public consumption. These are
      the only functions that we commit to maintaining for a Long
      Time. I'd therefore suggest sticking with require for both the
      functions and variables."

  This appears to affect the following packages:

  - Gnus (to support MH folders)
  - desktop (to save/restore session state, I think)
  - ispell (so that it can filter out quotation prefix strings?)
  - Supercite
  - mailcrypt
  - tm
  - Gnats
  - Hyperbole
  - BBDB

** tm

  MH-E now uses Gnus for MIME support.  The MH-E support in tm should
  just go away, and anyone still using tm with MH-E should stop.

** hyperbole

  It's unclear whether Hyperbole works with MH-E 7, so I didn't try to
  fix it to work with MH-E 8.

* incompatibilities between MH-E and XEmacs package practice

  MH-E assumes that the compile-time environment is the same as the
  runtime environment, so it does some compile-time optimizations
  (feature checks) that aren't appropriate for XEmacs.

  The XEmacs package system leads to a filesystem layout that is
  different from what the upstream MH-E expects.  In particular, the
  upstream code expects icons and other images in etc/images; it needs
  to look in etc/mh-e on XEmacs.

* other brokenness

** speedbar

  The speedbar support in XEmacs appears to be broken in both MH-E 7
  and 8: it doesn't reliably update to show folders.

** font-lock hangs

  I ran into a problem where MH-E would fontify the headers in letter
  mode (draft email), and then deleting a header line would put XEmacs
  into a tight loop.  This was awhile ago, so maybe it's been fixed
  since then.  I tried debugging it, but I ran into Issue416 and gave
  up.

** custom-load

  The MH-E declarations for Customize are invoked via wrapper macros.
  These macros need to be defined when custom-load.el is generated.
  In the upstream code the macros live in mh-e.el, and loading mh-e.el
  has part of the custom-load.el generation doesn't work for some
  reason.  So I moved the macros to their own file
  (mh-custom-macros.el).