RE: master 1e3b0f2: Improve doc strings of project.el

[Drew Adams <drew.adams@oracle.com>]

(Caveat: I haven't been following this thread, I'll
likely continue to not follow it, and I know almost
nothing about project.el.)

From one msg:

> > And bookmarks/switch-to-buffer/registers are not good
> > options for this goal?
> 
> The problem I raised is that such a Grep buffer will not be offered as
> a completion candidate when it is definitely relevant to my work on a
> project.  You suggest that I don't use the project.el commands, which
> is exactly what bothers me: it means that project.el commands don't
> support well a very simple project-related activity, which for me is
> a very frequent one.

From another msg:

> I proposed to find a different way of telling which buffer is related
> to a project, other than by looking at its default-directory.  We
> could design a way of doing that which would then support adding
> buffers to a project quite easily.  But Dmitry doesn't think we should
> go that way.
> 
> More to the point, my question is how would adding a buffer to the
> project be recorded and where, under your proposal?

I imagine that project.el defines a project as including
something like these things, and perhaps some other stuff:

1. A set of files.
2. Possibly a set of other Emacs/Lisp objects: buffers,
   vars, whatever.
3. Associations among such things, and among them and
   other things, including things (e.g. tools) outside
   Emacs.

I imagine that project.el can persist a project.

I'll just mention that bookmarks, bookmark files, and
bookmark-list displays are objects that can be persisted.

A bookmark can record nearly anything: a set of variables,
a location or set of locations,... anything.

Bookmark+ takes advantage of this generality in ways that
could be useful for project mgt.  I mention this because
vanilla Emacs bookmarks could too.  I'm not proposing
using Bookmark+, but just mentioning some of what you can
do using bookmarks that I think can be relevant to
working with or defining projects.

You can bookmark a Dired buffer, with its markings,
omit-set, switches, inserted subdirs, hidden subdirs, etc.
And Dired can list an arbitrary set of files and dirs; it
need not show only part of a single tree.

You can bookmark a set of Dired bookmarks that represent
a dir hierarchy and are opened together.

You can bookmark buffers, and locations in them.  Of
course, if restored from persistence the bookmark must
know how to regenerate the buffer.

One thing I haven't gotten around to implementing, but
is possible, is to bookmark the marked buffers in either
Ibuffer or Buffer Menu.  (Again, supposing knowledge of
how to regenerate or recuperate the buffer in a new
session.)

You can bookmark a function.  For example, a bookmark to
restore a given `*grep*' listing, by recomputing it,
records a function that performs the given `grep'
invocation.

From a `grep', `occur', compilation, etc. buffer you can
bookmark one or more of the individual hits, so that
jumping to such a bookmark takes you to the hit destination
(e.g. position in the grepped file).

You can bookmark all hits visible in the `grep', `occur',
etc. buffer, so after editing to remove some hits you can
get the effect of having "marked" some and then bookmarked
each of the marked ones.

In Dired, you can bookmark each of the marked files or
dirs.

In the bookmark-list display, you can dired the marked
bookmarks, i.e., create a Dired buffer with just the
files and dirs that are the targets of the marked
bookmarks.

You can bookmark a bookmark-list display itself (what
`C-x r l' shows).  This includes filtering, sorting, etc.

You can bookmark a bookmark file, so that jumping to
the bookmark switches to that set of bookmarks or loads
them additionally.

There are bookmark jump commands specific to different
types or sets of bookmarks.  E.g. jump to the bookmarks
for a specific project, choosing only among "project"
bookmarks.

There are many ways to define a project in this regard.
One is to mark the "project" bookmarks in a bookmark
list and use `C-c C-j' to define a command that jumps
to them (they are the only completion candidates).

You can bookmark a desktop.

Besides bookmark-file bookmarks, bookmark-list bookmarks,
Dired bookmarks, desktop bookmarks, etc., as ways of
organizing bookmarks into sets (~projects), you have
tags.

You can tag any set of bookmarks any way you like,
including with any Lisp object as tag value instead
of just a string.  You can list or complete against
bookmarks that have certain combinations of tags.

So your wanting to get to a `*grep*' buffer that
belongs to a given project is realized trivially:
just tag it for the project, then use a command that
jumps to a bookmark with that tag (i.e., only those
bookmarks are completion candidates).

Tags are the most flexible way to organize bookmarks.

You can even use bookmarks to tag files or other
objects in various ways just for purposes of
organizing them, whether or not you ever use the
bookmarks as a way to visit them.

Different projects can have different tags for the
same sets of files, directories,..., whatever.  No
need for copies - just different tagging.  Bookmarks
are persistent pointers.

If a "project" is mostly about grouping things to be
able to act on them together (search, visit, apply a
tool, etc.), and if a "project" should be able to be
persisted, then consider that you might do well to
leverage bookmarks - a flexible, open-ended way to
persist and restore or otherwise act on nearly
anything.

If "project" means code-development project for you,
or even if it means something else, what it does is
likely to be more or less a subset of what you can
do with bookmarks.  You might want to build features
for code-development project using, or on top of,
bookmarks.

And if you're thinking of adding very general
capabilities to project.el, you might want to think
instead about adding them at a more general level,
and then adapting them for the more specific use
for projects.

Just a thought.
____

For more info, search here for "project", "tag", or
any other terms used above:

https://www.emacswiki.org/emacs/BookmarkPlus