* DESCRIPTION (-*- allout -*- mode)

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

I find Emacs as a software development environment preferable to many
modern IDEs, particularly when using a richly-supported language like
Lisp or Emacs Lisp.  Sepia is my attempt to give Perl a similar degree
of support "in the Emacs way," which represents 40 years' collective
experience of the software development community.  I have therefore
tried throughout to use or mimic existing Emacs functionality, rather
than to create something new.

* INSTALLATION

1) run "perl Makefile.PL; make; make install"
2) optionally, install the Emacs-w3m and tree-widget packages:
       http://emacs-w3m.namazu.org/
       http://emhacks.sf.net/
3) put the elisp files somewhere Emacs will find them.

* RUNNING

In Emacs, type

   M-x load-library RET sepia RET
   M-x sepia-init RET

to start the interpreter.  For other features that require additional
emacs packages, you will have to manually load sepia-w3m and sepia-tree.

Probably the most useful part of the package is the cross-reference
facility.  Since it can take several seconds to create, and become
outdated when the program changes, it must be built explicitly by

   M-x sepia-rebuild RET

Type

   C-h f sepia-init RET

to get a list of Sepia functions.  The xref functions will look up
zero or more source locations, then allow you to cycle through them
with "M-x sepia-next".  With a prefix argument, the functions will
instead display a grep-mode buffer listing all the hits, from which
you can then navigate.

* TODO

.- (Easy) Use module, file, and line number to refine queries on the
   Perl side.
.- (Hard) Use module, file, and line number to filter results on the
   Emacs side.
.- (Easy) Clean up Perl side a bit more.
.- (Medium) Better documentation for Elisp side.
.- (Medium) Get the variable def/use analysis working again.

* 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.

* 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.