README

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