* DESCRIPTION (-*- org -*-)
Sepia is a set of features to make Emacs a better tool for Perl
development, including:

    * an interactive prompt (REPL) for evaluating code;
    * cross-referencing to find and navigate between function and
      variable definitions and uses;
    * variable- and function-name completion.
    * eldoc support to echo function arguments in the minibuffer
    * functions to simplify POD browsing with Emacs-w3m

Please see the Sepia.html or sepia.info for documentation.
* INSTALLATION
The basic installation procedure is:

    1) run "perl Makefile.PL; make; make install"
    2) optionally, install w3m and Emacs-w3m
    3) put the elisp files somewhere Emacs will find them.

Sepia is developed on the latest version of GNU Emacs, which can be
obtained from CVS or as a prebuilt package on some platforms.  It can
run on other versions of Emacs, but may require additional packages.
** Requirements for GNU Emacs 22
*** (optional) emacs-w3m from http://emacs-w3m.namazu.org/
*** (optional) w3m from http://w3m.sourceforge.net/
*** (optional) snippet.el from http://www.kazmier.com/computer/snippet.el
** Additional requirements GNU Emacs 21
*** ido.el
    http://cvs.savannah.gnu.org/viewcvs/*checkout*/emacs/lisp/ido.el?root=emacs
*** FreeBSD may require the following packages:
    tree-widget-emacs21-2.0
    emacs-w3m-emacs21-1.4.4_2
    mule-ucs-emacs21-0.85.r3
    semi-emacs21-1.14.6_1
    wv-1.2.4
    xlhtml-0.5_1,1
    libgsf-1.14.3
    flim-emacs21-1.14.8
    apel-emacs21-10.7
    ja-nkf-2.05

* TODO
** implement mod_apropos
** improve output for sepia-module-* (modinfo functions)
** (Medium) better intro documentation for debugger
** (Easy) Use module, file, line to refine queries (Perl side)
** (Medium) Get the variable def/use analysis working again.
** (Hard) Use module, file, line to filter results (Emacs side)
** (Medium) Let sepia-next go backward
   Need to use a vector plus current index instead of a list for
   sepia-found.
** (Hard) return from anything in the debugger
   Make it possible to return from intermediate calls in the debugger.
   Returning from die() is not often useful.

   This can be done with a clever DB::sub, but that dramatically slows
   down execution.
** (Easy) Fix sepia-indent-or-complete abbrev expansion
   Currently "else<TAB>" both expands and completes.
** (Medium) fix `sepia-beginning-of-defun' and `sepia-end-of-defun'.
   While they work for "normal" sub definitions, they fail on
   definitions that are all on one line, e.g.

       sub foo { ... }
       sub bar {
           ...
       }
** (Medium) Fix string escaping when passing between Perl and Emacs
   IO::Scalar's README tickles a bug.
** (Medium) Make the debugger's "next" work
   "next" (as opposed to "step") assumes that the next statement after
   line $n is line $n+1, which isn't true for loops, blank lines,
   multi-line statements, etc.  Fix this somehow.
** (Medium) Make "finish" more reliable
   It currently assumes that the last breakable statement in a sub is
   one line before its end.
* KNOWN BUGS
** Function definition lines may occasionally all go completely wrong.
   Rebuilding the Xref database fixes this.
** The cursor may miss by several lines when jumping to a definition.
   This is hard to fix -- Perl doesn't give exact line numbers for sub
   defs, so we have to do some minor regex-searching.
** `sepia-var-assigns' doesn't work yet -- don't use it.
** named method calls are (mostly?) detected, but nothing smart is
   done about packages, so e.g. "new Foo" will result in listings for
   every instance of "new" in your program.
** the first value printed in the debugger is undef.  why?!
* CREDITS
Sepia would never have been possible without Software Libre, as many
key components have been stolen and adapted from other packages:

    * Sepia::Xref is taken from B::Xref.
    * sepia-w3m is taken from w3m-perldoc.
* COPYRIGHT AND LICENCE
Copyright (C) 2004-2008 by Sean O'Rourke

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, at the time at which this
version of Sepia was released.