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 This will give you an Xref database for the EPL process, and start the
  38 REPL.  Note that you should do this before opening a Perl file, since
  39 Sepia needs to install some hooks on `cperl-mode-hook'.
  40
  41 Probably the most useful part of the package is the cross-reference
  42 facility.  In a Perl buffer with Sepia enabled, type
  43
  44    C-h f sepia-init <ret>
  45
  46 to get a list of functions using it.  In general, the functions will
  47 look up zero or more source locations, then allow you to cycle
  48 through them with "M-x sepia-next".  With a prefix argument, the
  49 functions will instead display a grep-mode buffer listing all the
  50 hits, from which you can then navigate.
  51
  52 * TODO
  53
  54 .- (Easy) Use module, file, and line number to refine queries on the
  55    Perl side.
  56 .- (Hard) Use module, file, and line number to filter results on the
  57    Emacs side.
  58 .- (Medium) Clean up Perl side.
  59 .- (Hard) Merge with B::Xref.
  60 .- (Medium) Better documentation for Elisp side.
  61
  62 * BUGS
  63
  64 .- Emacs may display a "not enough arguments for format string" error.
  65    This is probably caused by some code passing a string containing a
  66    "%" as the first argument to `format', either in but I haven't
  67    tracked it down yet.
  68 .- Function definition lines may occasionally all go completely wrong.
  69    Rebuilding the Xref database fixes this.
  70 .- The cursor may miss by several lines when jumping to a definition.
  71    This is hard to fix -- Perl doesn't give exact line numbers for sub
  72    defs, so we have to do some minor regex-searching.
  73 .- `sepia-var-assigns' doesn't work yet -- don't use it.
  74 .- named method calls are (mostly?) detected, but nothing smart is
  75    done about packages, so e.g. "new Foo" will result in listings for
  76    every instance of "new" in your program.
  77
  78 * CREDITS
  79
  80 Sepia would never have been possible without Software Libre, as many
  81 key components have been stolen and adapted from other packages:
  82
  83     * generic-repl is taken from Slime;
  84     * Devel::Xref is taken from B::Xref;
  85     * sepia-w3m is taken from w3m-perldoc;