README

   1 * DESCRIPTION (-*- org -*-)
   2 Sepia is a set of features to make Emacs a better tool for Perl
   3 development, including:
   4
   5     * an interactive prompt (REPL) for evaluating code;
   6     * cross-referencing to find and navigate between function and
   7       variable definitions and uses;
   8     * variable- and function-name completion.
   9     * eldoc support to echo function arguments in the minibuffer
  10     * functions to simplify POD browsing with Emacs-w3m
  11
  12 Please see the Sepia.html or sepia.info for documentation.
  13 * INSTALLATION
  14 The basic installation procedure is:
  15
  16     1) run "perl Makefile.PL; make; make install"
  17     2) optionally, install w3m and Emacs-w3m
  18     3) put the elisp files somewhere Emacs will find them.
  19
  20 Sepia is developed on the latest version of GNU Emacs, which can be
  21 obtained from CVS or as a prebuilt package on some platforms.  It can
  22 run on other versions of Emacs, but may require additional packages.
  23 ** Requirements for GNU Emacs 22
  24 *** (optional) emacs-w3m from http://emacs-w3m.namazu.org/
  25 *** (optional) w3m from http://w3m.sourceforge.net/
  26 *** (optional) snippet.el from http://www.kazmier.com/computer/snippet.el
  27 ** Additional requirements GNU Emacs 21
  28 *** ido.el
  29     http://cvs.savannah.gnu.org/viewcvs/*checkout*/emacs/lisp/ido.el?root=emacs
  30 *** FreeBSD may require the following packages:
  31     tree-widget-emacs21-2.0
  32     emacs-w3m-emacs21-1.4.4_2
  33     mule-ucs-emacs21-0.85.r3
  34     semi-emacs21-1.14.6_1
  35     wv-1.2.4
  36     xlhtml-0.5_1,1
  37     libgsf-1.14.3
  38     flim-emacs21-1.14.8
  39     apel-emacs21-10.7
  40     ja-nkf-2.05
  41
  42 * DEVELOPMENT
  43 The "official" source code repository mirror is at
  44
  45     http://repo.or.cz/w/sepia.git
  46
  47 To get a copy, install Git, then
  48
  49     git clone git://repo.or.cz/sepia.git
  50
  51 To submit a patch, please send a diff to the author, including an
  52 Emacs-style ChangeLog entry.
  53 * TODO
  54 ** (Easy) Use module, file, line to refine queries (Perl side)
  55 ** (Medium) Get the variable def/use analysis working again.
  56 ** (Hard) Use module, file, line to filter results (Emacs side)
  57 ** (Medium) Let sepia-next go backward
  58    Need to use a vector plus current index instead of a list for
  59    sepia-found.
  60 ** (Hard) return from anything in the debugger
  61    Make it possible to return from intermediate calls in the debugger.
  62    Returning from die() is not often useful.
  63
  64    This can be done with a clever DB::sub, but that dramatically slows
  65    down execution.
  66 ** (Medium) fix `sepia-beginning-of-defun' and `sepia-end-of-defun'.
  67    While they work for "normal" sub definitions, they fail on
  68    definitions that are all on one line, e.g.
  69
  70        sub foo { ... }
  71        sub bar {
  72            ...
  73        }
  74 ** (Medium) Fix string escaping when passing between Perl and Emacs
  75    IO::Scalar's README tickles a bug.
  76 ** (Hard) Make the debugger's "next" work
  77    "next" (as opposed to "step") assumes that the next statement after
  78    line $n is line $n+1, which isn't true for loops, blank lines,
  79    multi-line statements, etc.  Fix this somehow.  One way might be to
  80    temporary regain control on a op_next/op_nextstate, or whatever
  81    those are called, but this would be hard and/or require XS.
  82 ** (Medium) Make "finish" more reliable
  83    It currently assumes that the last breakable statement in a sub is
  84    one line before its end.  The "right" solution would be like above:
  85    to hook op_leave temporarily.  This would similarly require XS
  86    trickery.
  87 ** (Medium) Enable partial-word completion of lexicals
  88 ** (Hard) Rewrite completion code, which is pretty ugly now.
  89    This wouldn't seem "hard" but, having hacked on two completion
  90    codebases (Sepia's and complete.el's), I know there are always a
  91    lot of subtle cases to get right, and what acts "naturally" by
  92    human standards is extremely complicated to specify in code.
  93 ** (Hard) Add appropriate hooks
  94    Possibly update existing functions to make use of hooks for better
  95    modularity.
  96 * KNOWN BUGS
  97 The following is a list of bugs that are difficult to automatically
  98 reproduce, with the dates they were first observed.
  99 ** (2006-05-19) Function definition lines occasionally all go wrong.
 100    Rebuilding the Xref database fixes this.
 101 ** (2006-05-19) The cursor misses by several lines jumping to a definition.
 102    This is hard to fix -- Perl doesn't give exact line numbers for sub
 103    defs, so we have to do some minor regex-searching.
 104 ** (2006-05-19) `sepia-var-assigns' doesn't work yet -- don't use it.
 105 ** (2006-05-19) named method calls (mostly?) detected, but naively.
 106    Nothing smart is done about packages, so e.g. "new Foo" will result
 107    in listings for every instance of "new" in your program.
 108 ** (2008-01-18) the first value printed in the debugger is undef.  why?!
 109 ** (2009-12-13) completion deletes things it shouldn't
 110    e.g. $x->method => method.  I need to rewrite this code to not suck.
 111 * COPYRIGHT AND LICENCE
 112 Copyright (C) 2004-2009 Sean O'Rourke
 113
 114 This library is free software; you can redistribute it and/or modify
 115 it under the same terms as Perl itself, at the time at which this
 116 version of Sepia was released.