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 * TODO
  43 ** implement mod_apropos
  44 ** improve output for sepia-module-* (modinfo functions)
  45 ** (Medium) better intro documentation for debugger
  46 ** (Easy) Use module, file, line to refine queries (Perl side)
  47 ** (Medium) Get the variable def/use analysis working again.
  48 ** (Hard) Use module, file, line to filter results (Emacs side)
  49 ** (Medium) Let sepia-next go backward
  50    Need to use a vector plus current index instead of a list for
  51    sepia-found.
  52 ** (Hard) return from anything in the debugger
  53    Make it possible to return from intermediate calls in the debugger.
  54    Returning from die() is not often useful.
  55
  56    This can be done with a clever DB::sub, but that dramatically slows
  57    down execution.
  58 ** (Easy) Fix sepia-indent-or-complete abbrev expansion
  59    Currently "else<TAB>" both expands and completes.
  60 ** (Medium) fix `sepia-beginning-of-defun' and `sepia-end-of-defun'.
  61    While they work for "normal" sub definitions, they fail on
  62    definitions that are all on one line, e.g.
  63
  64        sub foo { ... }
  65        sub bar {
  66            ...
  67        }
  68 ** (Medium) Fix string escaping when passing between Perl and Emacs
  69    IO::Scalar's README tickles a bug.
  70 ** (Medium) Make the debugger's "next" work
  71    "next" (as opposed to "step") assumes that the next statement after
  72    line $n is line $n+1, which isn't true for loops, blank lines,
  73    multi-line statements, etc.  Fix this somehow.
  74 ** (Medium) Make "finish" more reliable
  75    It currently assumes that the last breakable statement in a sub is
  76    one line before its end.
  77 * KNOWN BUGS
  78 ** Function definition lines may occasionally all go completely wrong.
  79    Rebuilding the Xref database fixes this.
  80 ** The cursor may miss by several lines when jumping to a definition.
  81    This is hard to fix -- Perl doesn't give exact line numbers for sub
  82    defs, so we have to do some minor regex-searching.
  83 ** `sepia-var-assigns' doesn't work yet -- don't use it.
  84 ** named method calls are (mostly?) detected, but nothing smart is
  85    done about packages, so e.g. "new Foo" will result in listings for
  86    every instance of "new" in your program.
  87 ** the first value printed in the debugger is undef.  why?!
  88 * CREDITS
  89 Sepia would never have been possible without Software Libre, as many
  90 key components have been stolen and adapted from other packages:
  91
  92     * Sepia::Xref is taken from B::Xref.
  93     * sepia-w3m is taken from w3m-perldoc.
  94 * COPYRIGHT AND LICENCE
  95 Copyright (C) 2004-2008 by Sean O'Rourke
  96
  97 This library is free software; you can redistribute it and/or modify
  98 it under the same terms as Perl itself, at the time at which this
  99 version of Sepia was released.