branch: externals/ement
commit 284db78e79353526efd051f2533925b6ac787d3a
Author: Adam Porter <a...@alphapapa.net>
Commit: Adam Porter <a...@alphapapa.net>
Docs: Tidy
---
README.org | 35 ++++++++++++++++++-----------------
1 file changed, 18 insertions(+), 17 deletions(-)
diff --git a/README.org b/README.org
index bcd0fefba3..8d837c5bb1 100644
--- a/README.org
+++ b/README.org
@@ -32,7 +32,6 @@ Feel free to join us in the chat room:
[[https://matrix.to/#/#ement.el:matrix.or
- [[#bindings][Bindings]]
- [[#tips][Tips]]
- [[#encrypted-room-support-through-pantalaimon][Encrypted room support
through Pantalaimon]]
-- [[#rationale][Rationale]]
- [[#changelog][Changelog]]
- [[#development][Development]]
:END:
@@ -276,22 +275,6 @@ Ement.el doesn't support encrypted rooms natively, but it
can be used transparen
(ement-connect :uri-prefix "http://localhost:8009";)
#+END_SRC
-* Rationale
-
-Why write a new Emacs Matrix client when there is already
[[https://github.com/alphapapa/matrix-client.el][matrix-client.el]], by the
same author, no less? A few reasons:
-
-- ~matrix-client~ uses an older version of the Matrix spec, r0.3.0, with a few
elements of r0.4.0 grafted in. Bringing it up to date with the current version
of the spec, r0.6.1, would be more work than to begin with the current version.
Ement.el targets r0.6.1 from the beginning.
-- ~matrix-client~ does not use Matrix's lazy-loading feature (which was added
to the specification later), so initial sync requests can take a long time for
the server to process and can be large (sometimes tens of megabytes of JSON for
the client to process!). Ement.el uses lazy-loading, which significantly
improves performance.
-- ~matrix-client~ automatically makes buffers for every room a user has
joined, even if the user doesn't currently want to watch a room. Ement.el
opens room buffers on-demand, improving performance by not having to insert
events into buffers for rooms the user isn't watching.
-- ~matrix-client~ was developed without the intention of publishing it to,
e.g. MELPA or ELPA. It has several dependencies, and its code does not always
install or compile cleanly due to macro-expansion issues (apparently depending
on the user's Emacs config). Ement.el is designed to have minimal dependencies
outside of Emacs (currently only one, ~plz~, which could be imported into the
project), and every file is linted and compiles cleanly using
[[https://github.com/alphapapa/makem.sh [...]
-- ~matrix-client~ uses EIEIO, probably unnecessarily, since few, if any, of
the benefits of EIEIO are realized in it. Ement.el uses structs instead.
-- ~matrix-client~ uses bespoke code for inserting messages into buffers, which
works pretty well, but has a few minor bugs which are difficult to track down.
Ement.el uses Emacs's built-in (and perhaps little-known) ~ewoc~ library, which
makes it much simpler and more reliable to insert and update messages in
buffers, and enables the development of advanced UI features more easily.
-- ~matrix-client~ was, to a certain extent, designed to imitate other
messaging apps. The result is, at least when used with the
~matrix-client-frame~ command, fairly pleasing to use, but isn't especially
"Emacsy." Ement.el is intended to better fit into Emacs's paradigms.
-- ~matrix-client~'s long name makes for long symbol names, which makes for
tedious, verbose code. ~ement~ is easy to type and makes for concise, readable
code.
-- The author has learned much since writing ~matrix-client~ and hopes to write
simpler, more readable, more maintainable code in Ement.el. It's hoped that
this will enable others to contribute more easily.
-
-Note that, while ~matrix-client~ remains usable, and probably will for some
time to come, Ement.el has now surpassed it in every way. The only reason to
choose ~matrix-client~ instead is if one is using an older version of Emacs
that isn't supported by Ement.el.
-
* Changelog
:PROPERTIES:
:TOC: :depth 0
@@ -596,6 +579,24 @@ Ement.el is published in GNU ELPA and is considered part
of GNU Emacs. Therefor
An Org-formatted version of the Matrix spec is available in the
[[https://github.com/alphapapa/ement.el/tree/meta/spec][meta/spec]] branch.
+** Rationale
+
+/This section is preserved for posterity. As it says, Ement.el has long since
surpassed ~matrix-client~, which should no longer be used./
+
+Why write a new Emacs Matrix client when there is already
[[https://github.com/alphapapa/matrix-client.el][matrix-client.el]], by the
same author, no less? A few reasons:
+
+- ~matrix-client~ uses an older version of the Matrix spec, r0.3.0, with a few
elements of r0.4.0 grafted in. Bringing it up to date with the current version
of the spec, r0.6.1, would be more work than to begin with the current version.
Ement.el targets r0.6.1 from the beginning.
+- ~matrix-client~ does not use Matrix's lazy-loading feature (which was added
to the specification later), so initial sync requests can take a long time for
the server to process and can be large (sometimes tens of megabytes of JSON for
the client to process!). Ement.el uses lazy-loading, which significantly
improves performance.
+- ~matrix-client~ automatically makes buffers for every room a user has
joined, even if the user doesn't currently want to watch a room. Ement.el
opens room buffers on-demand, improving performance by not having to insert
events into buffers for rooms the user isn't watching.
+- ~matrix-client~ was developed without the intention of publishing it to,
e.g. MELPA or ELPA. It has several dependencies, and its code does not always
install or compile cleanly due to macro-expansion issues (apparently depending
on the user's Emacs config). Ement.el is designed to have minimal dependencies
outside of Emacs (currently only one, ~plz~, which could be imported into the
project), and every file is linted and compiles cleanly using
[[https://github.com/alphapapa/makem.sh [...]
+- ~matrix-client~ uses EIEIO, probably unnecessarily, since few, if any, of
the benefits of EIEIO are realized in it. Ement.el uses structs instead.
+- ~matrix-client~ uses bespoke code for inserting messages into buffers, which
works pretty well, but has a few minor bugs which are difficult to track down.
Ement.el uses Emacs's built-in (and perhaps little-known) ~ewoc~ library, which
makes it much simpler and more reliable to insert and update messages in
buffers, and enables the development of advanced UI features more easily.
+- ~matrix-client~ was, to a certain extent, designed to imitate other
messaging apps. The result is, at least when used with the
~matrix-client-frame~ command, fairly pleasing to use, but isn't especially
"Emacsy." Ement.el is intended to better fit into Emacs's paradigms.
+- ~matrix-client~'s long name makes for long symbol names, which makes for
tedious, verbose code. ~ement~ is easy to type and makes for concise, readable
code.
+- The author has learned much since writing ~matrix-client~ and hopes to write
simpler, more readable, more maintainable code in Ement.el. It's hoped that
this will enable others to contribute more easily.
+
+Note that, while ~matrix-client~ remains usable, and probably will for some
time to come, Ement.el has now surpassed it in every way. The only reason to
choose ~matrix-client~ instead is if one is using an older version of Emacs
that isn't supported by Ement.el.
+
* License
:PROPERTIES:
:TOC: :ignore (this)
