README

   1 * DESCRIPTION (-*- org -*-)
   2
   3 Sepia is a set of features to make Emacs a better tool for Perl
   4 development, including:
   5
   6     * an interactive prompt (REPL) for evaluating code;
   7     * cross-referencing to find and navigate between function and
   8       variable definitions and uses;
   9     * variable- and function-name completion.
  10     * eldoc support to echo function arguments in the minibuffer
  11     * functions to simplify POD browsing with Emacs-w3m
  12
  13 I find Emacs as a software development environment preferable to many
  14 modern IDEs, particularly when using a richly-supported language like
  15 Lisp or Emacs Lisp.  Sepia is my attempt to give Perl a similar degree
  16 of support "in the Emacs way," which represents 40 years' collective
  17 experience of the software development community.  I have therefore
  18 tried throughout to use or mimic existing Emacs functionality, rather
  19 than to create something new.
  20
  21 * INSTALLATION
  22
  23 1) run "perl Makefile.PL; make; make install"
  24 2) optionally, install the Emacs-w3m and tree-widget packages:
  25        http://emacs-w3m.namazu.org/
  26        http://emhacks.sf.net/
  27 3) put the elisp files somewhere Emacs will find them.
  28
  29 * RUNNING
  30
  31 In Emacs, type
  32
  33    M-x load-library RET sepia RET
  34    M-x sepia-init RET
  35
  36 to start the interpreter.  For other features that require additional
  37 emacs packages, you will have to manually load sepia-w3m and sepia-tree.
  38
  39 Probably the most useful part of the package is the cross-reference
  40 facility.  Since it can take several seconds to create, and become
  41 outdated when the program changes, it must be built explicitly by
  42
  43    M-x sepia-rebuild RET
  44
  45 Type
  46
  47    C-h f sepia-init RET
  48
  49 to get a list of Sepia functions.  The xref functions will look up
  50 zero or more source locations, then allow you to cycle through them
  51 with "M-x sepia-next".  With a prefix argument, the functions will
  52 instead display a grep-mode buffer listing all the hits, from which
  53 you can then navigate.
  54
  55 * TODO
  56
  57 ** (Easy) Use module, file, and line number to refine queries on the
  58    Perl side.
  59 ** (Hard) Use module, file, and line number to filter results on the
  60    Emacs side.
  61 ** (Easy) Clean up Perl side a bit more.
  62 ** (Medium) Better documentation for Elisp side.
  63 ** (Medium) Get the variable def/use analysis working again.
  64
  65 * BUGS
  66
  67 ** Function definition lines may occasionally all go completely wrong.
  68    Rebuilding the Xref database fixes this.
  69 ** The cursor may miss by several lines when jumping to a definition.
  70    This is hard to fix -- Perl doesn't give exact line numbers for sub
  71    defs, so we have to do some minor regex-searching.
  72 ** `sepia-var-assigns' doesn't work yet -- don't use it.
  73 ** named method calls are (mostly?) detected, but nothing smart is
  74    done about packages, so e.g. "new Foo" will result in listings for
  75    every instance of "new" in your program.
  76
  77 * CREDITS
  78
  79 Sepia would never have been possible without Software Libre, as many
  80 key components have been stolen and adapted from other packages:
  81
  82     * Sepia::Xref is taken from B::Xref.
  83     * sepia-w3m is taken from w3m-perldoc.