[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[nongnu] elpa/sesman e83fcfd939 002/100: Add readme
From: |
ELPA Syncer |
Subject: |
[nongnu] elpa/sesman e83fcfd939 002/100: Add readme |
Date: |
Tue, 28 Dec 2021 14:05:57 -0500 (EST) |
branch: elpa/sesman
commit e83fcfd9399a75586cb713128bceb845252ba9e5
Author: Vitalie Spinu <spinuvit@gmail.com>
Commit: Vitalie Spinu <spinuvit@gmail.com>
Add readme
---
README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 54 insertions(+)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000000..d03390c234
--- /dev/null
+++ b/README.md
@@ -0,0 +1,54 @@
+
+## Generic session manager for Emacs
+
+This is a brief overview. Please see the code for more details.
+
+Sesman provides facilities for session management and interactive session
association with current contexts. While "sessions" is a broad and
implementation specific concept, the primary target of `sesman` are Emacs based
IDEs ([CIDER][], [ESS][], [Geiser][], [Robe][], [SLIME][] etc.)
+
+For Emacs based IDEs, session is commonly composed of one or more physical
processes (sub-processes, sockets, websockets etc). For example in the current
implementation of [CIDER][] a session would be composed of one or more cider
connections (Clojre or ClojureScript). Each [CIDER][] connection consists of
user REPL buffer and two processes, one for user eval communication and another
for tooling (completion, inspector etc).
+
+### Concepts:
+
+ - "session" is a list of the form `(session-name ..other-stuff..)` where
`..other-stuff..` is system dependent.
+ - "system" is generic name used for the tools which uses sesman (e.g.
`CIDER`, `ESS` etc)
+ - "contexts" are Emacs objects which describe current context. For example
`current-buffer`, `default-directory` and `project-current` are such contexts.
Context objects are used to create associations (links) between the current
context and sessions. At any given time the user can link/unlink sessions
to/from contexts. By default there are three types of contexts - buffer,
directory and project, but systems can define their own contexts as they see
fit.
+
+Sesman is composed of two parts, [user interface][], available as [sesman
map][], and [system interface][] consisting of a few generic functions which
systems should define.
+
+### [User Interface][]
+
+Consists of
+
+ - lifecycle management commands (`sesman-start`, `sesman-kill` and
`sesman-restart`), and
+ - association management commands (`sesman-link-with-buffer`,
`sesman-link-with-directory`, `sesman-link-with-project` and `sesman-unlink`).
+
+From the user's prospective the work-flow is simple. Start a session, either
with `sesman-start` (`C-c C-s C-s`) or some of the system specific commands
(`run-xyz`, `xyz-jack-in` etc). On startup each session is automatically
associated with the least specific context (commonly a project). In the most
common case the user has one session open per project; thus, no ambiguity
arises when the system retrieves current session. If none or multiple sessions
are associated with current context, [...]
+
+Currently there is only one custom variable, `sesman-1-to-1-links`, which
lists context types for which `1-to-1` associations are desired (defaults to
`'(directory buffer)`. This means, that each time the user links a session with
a directory, any previous associations with that directory are lost. For
context types not in this list (e.g. `project`), 1-to-many associations are
allowed.
+
+### [System Interface][]
+
+Consists of several generics, of which only first two are strictly required:
+
+ - `sesman-start-session`
+ - `sesman-kill-session`
+ - `sesman-restart-session` - defaults to `sesman-start-session` +
`sesman-kill-session`
+ - `sesman-greater-p` - used for sorting sessions in "recency" order
+ - `sesman-friendly-session-p` - used to define friendly sessions (such as
projects which are dependencies of other projects)
+
+Depending on the purpose, sesman system can use several functions to retrieve
sessions (`sesman-ensure-session`, `sesman-linked-sessions`,
`sesman-friendly-sessions`, `sesman-system-sessions` and `sesman-sessions`).
Most important of these being `sesman-ensure-session` which should be used to
ensure that at least one session is linked to the current context. It returns
the most specific session given sesman associations already in place. In case
of ambiguity (or no sessions) the user is [...]
+
+Systems could directly use user level commands to manage sessions
(`sesman-start`, `sesman-kill`) or use legacy system specific initializer
(`run-xyz`, `xyz-jack-in` etc). In the latter case, systems should call
`sesman-register` to register their sessions with `sesman`.
+
+Systems should link [semsna map][] into their modes' key-maps (ideally on `C-c
C-s`, which is a good mnemonic, is free in CIDER and already does similar
things in ESS).
+
+
+[user interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L53
+[system interface]: https://github.com/vspinu/sesman/blob/master/sesman.el#L133
+[sesman map]: https://github.com/vspinu/sesman/blob/master/sesman.el#L112-L130
+
+[cider]: https://github.com/clojure-emacs/cider
+[ess]: https://ess.r-project.org/
+[geiser]: https://github.com/jaor/geiser
+[robe]: https://github.com/dgutov/robe
+[slime]: https://common-lisp.net/project/slime/
- [nongnu] branch elpa/sesman created (now e0f555f963), ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 6aa04521eb 012/100: Add badges, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0f6eadfb1a 004/100: Idem, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman b27755c150 003/100: Major update before cider integration, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman e83fcfd939 002/100: Add readme,
ELPA Syncer <=
- [nongnu] elpa/sesman 4f52cccf26 013/100: Update readme, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman fea061de16 007/100: Add sesman menu, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman a39f0e2c1b 015/100: Add commentary, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 13f7748b9f 017/100: Rename sesman-single-link-contexts -> sesman-single-link-context-types, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0303d66f0e 019/100: Rename link accessors --link- -> --lnk- to avoid naming confusion, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 0f86bd3d34 021/100: Rename sesman-ensure-linked-session -> sesman-ensure-session, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 43b0c9ef2a 026/100: [Fix #4] Rename lingering sesman-ensure-linked-session, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman fb4d2784f3 025/100: Fix typo in README, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 16be56c643 032/100: Add a missing :package-version to a defcustom, ELPA Syncer, 2021/12/28
- [nongnu] elpa/sesman 4229e2128c 027/100: Replace a redundant let*, ELPA Syncer, 2021/12/28