=pod

I have been working on L<eproject|http://github.com/jrockway/eproject>
somewhat extensively again, and have added a ton of features and
documentation.  I have split eproject into two files, C<eproject.el>
for the "plumbing", and C<eproject-extras.el> for the "porcelain".
You will need to C<(require 'eproject-extras)> now, if you want the
shiny convenience features (rather than just the core).

The goal of eproject is to provide project-specific metadata to each
buffer (file) that is a member of the project.  In past versions, each
project had a type ("perl", "generic-git", etc.) and all metadata was
inherited by the project buffers from the type definition.  This
worked nicely for things that were project-type-specific (like the
list of file extensions to ignore), but was not for things that were
project-specific (like whether or not the Perl classes should use
MooseX::Declare).  I extended the concept of metadata by adding
"instance metadata".  Types can define a metadata as a function of one
argument (the project root), which will be evaluated with the project
root and the value stored as the project-specific value.  As an
example, metadata like:

   :foo "bar" :root (lambda (root) root)

will be translated to:

   :foo "bar" :root "/path/to/your/project/"

You can do something more complex, of course, like determining whether
or not to use MooseX::Declare.  (See
L<here|http://wiki.github.com/jrockway/eproject/eproject-for-perl> for
a detailed explanation of this particular case.)

This makes the project metadata much more useful.

I have also added two more ways to add metadata to a project.  (The
original way (type-specific metadata keys) still works, too.)

The first new way is a C<.eproject> file in the project root
directory.  If this exists, its contents will be treated as a plist
(key/value pairs) to be merged in with the type metadata.  This lets
project authors distribute project metadata with the project, without
having to invent their own format.  (This is a better idea than
putting buffer-local-variables in every file; just put them in the
.eproject file, and set up mode hooks that inspect that data and do
the right thing.  "Don't repeat yourself!")

(This really cleans things up for me.  I used to make a
".mxdeclare_project" file in the project root to indicate to some
ad-hoc function that this project uses MX::Declare.  Now I can just
set the key in the .eproject file, and throw away all the ad-hoc code
I wrote to support that.  I love deleting code, especially if I wrote
it!)

The second new way is via a C<(define-project-attribute ...)> call in
your Emacs init file.  This lets you define rules, based on the
project name or location, for specific projects.  An example of this
in action is
L<here|http://wiki.github.com/jrockway/eproject/project-attributes>.
When a project is called "xmms2-devel", I set a flag.  Later on, my
C<c-mode-hook> looks for that flag.  If it's set, I change the
indentation settings for that specific project (as it's different from
my usual C style).

I think this unifies all the functionality provided by other Emacs
project manager libraries.  You can pick-and-choose the parts you
want, and interact with them via a common API.  (Which is described in
detail on the wiki, and in the eproject.el source code.)

So that's it for major internals changes.  I cleaned up I<a lot> of
code, and now Windows is supported.  Dired buffers that are inside of
a project will also have eproject-mode turned on now.  (A bug was
preventing this in past versions.)

That is just the internals, though... I also made user-visible
changes. :)

There are now 5 main utility functions that build on the eproject core
to provide useful features.  They live in the C<eproject-extras.el>
file.  (Use these as an example for writing your own eproject
extensions.)

The first function is C<eproject-ibuffer>.  It will open an ibuffer
window that only shows files that are a member of the current project.
You can execute it with a prefix argument (hit C-u, then run the
command normally), and it will prompt you for a project.  (This works
even when you are outside of a project.)  Ibuffer is also aware of
eprojects, now, and you can filter any ibuffer listing with
C<ibuffer-filter-by-eproject> or C<ibuffer-filter-by-eproject-root>.

There are two more bulk management functions,
C<eproject-kill-project-buffers> and
C<eproject-open-all-project-files>.  They both work on the current
project, or, if given a prefix argument, will prompt you for a project
instead.  The first function kills all buffers that are a member of
the current project; the second function will open all files that are
a member of the current (or selected) project.  The first is very
useful when you are done with something, and want to cleanup
unnecessary buffers.  The second is nice for starting your day -- no
need to worry about opening all the files; which seems to be how it
ends up eventually... just let emacs do it for you.  (Remember, you
can easily manage the set of buffers with C<eproject-ibuffer>.)

The next function is C<eproject-revisit-project>.  If you close all
your project files, this function will let you reopen one (or the
project root).  It's an alternative to
C<eproject-open-all-project-files>, which might clutter things up
excessively.

The last function is the reason I wrote Eproject, and has been around
since the very first version.  It's C<eproject-find-file>.  It will
open up a list of all files in the current project, and let you visit
it with just a few keystrokes.  I can't live without it.

Anyway, I think that's it.  There is a lot of documentation now, both
in the source code files, and on the
L<wiki|http://wiki.github.com/jrockway/eproject>.  If you have
questions, problems, or patches; you can email me, find me on #emacs
(jrockway), or open up a problem ticket on github.

Share and enjoy!  (And send me your language type definitions -- I
will make them part of the next release.)