#+TITLE: ement [[images/logo64.png]] #+PROPERTY: LOGGING nil # Note: This readme works with the org-make-toc package, which automatically updates the table of contents. # [[https://melpa.org/#/package-name][file:https://melpa.org/packages/package-name-badge.svg]] [[https://stable.melpa.org/#/package-name][file:https://stable.melpa.org/packages/package-name-badge.svg]] Ement.el is a new Matrix client for Emacs. It's basic at the moment, but it can be used to send and read messages. * Screenshots The default style resembles IRC clients, with each message being prefixed by the username (which enables powerful Emacs features, like using Occur to show all messages from or mentioning a user): [[images/screenshot5.png]] Note that the colored message text is off by default, enabled by customizing =M-x customize-option RET ement-room-prism=. An alternative style, with usernames displayed above groups of messages, is easily selectable in the option ~ement-room-message-format-spec~: [[images/screenshot2.png]] The message formatting is highly customizeable (e.g. the timestamp can be displayed in the left or right margin), and timestamp headers are displayed where a certain amount of time passes between events. * Contents :noexport: :PROPERTIES: :TOC: :include siblings :END: :CONTENTS: - [[#rationale][Rationale]] - [[#installation][Installation]] - [[#usage][Usage]] - [[#changelog][Changelog]] - [[#development][Development]] - [[#license][License]] :END: * 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][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. However, note that ~matrix-client~ is a more mature client and is very reliable in the author's experience. While Ement.el is intended to reach feature parity with it and eventually surpass it, that will take some time, so ~matrix-client~ remains a good choice. * Installation :PROPERTIES: :TOC: :depth 0 :END: # ** MELPA # # If you installed from MELPA, you're done. Just run one of the commands below. ** Quelpa The recommended way to install is with [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this: #+BEGIN_SRC elisp ;; Install and load `quelpa-use-package'. (package-install 'quelpa-use-package) (require 'quelpa-use-package) ;; Install `plz' HTTP library (not on MELPA yet). (use-package plz :quelpa (plz :fetcher github :repo "alphapapa/plz.el")) ;; Install Ement. (use-package ement :quelpa (ement :fetcher github :repo "alphapapa/ement.el")) #+END_SRC ** Straight Using [[https://github.com/raxod502/straight.el][Straight]], it's also very simple: #+BEGIN_SRC elisp ;; Install `plz' HTTP library (not on MELPA yet). (use-package plz :straight (plz :fetcher github :repo "alphapapa/plz.el")) ;; Install Ement. (use-package ement :straight (ement :fetcher github :repo "alphapapa/ement.el")) #+END_SRC ** Manual If you want to install it manually, it's simple enough, but you should know what you're doing, and you're on your own. * Usage :PROPERTIES: :TOC: :depth 0 :END: 1. Call command ~ement-connect~ to connect. 2. Wait for initial sync to complete (which can take a few moments--initial sync JSON requests can be large). 3. Use these commands: - ~ement-view-room~ to select a room buffer to view, with completion. - ~ement-list-rooms~ to view the list of joined rooms. In a room buffer: - ~RET~ to write a new message. - ~S-RET~ writes a reply to the message at point. - ~TAB~ / ~~ moves between messages. - ~v~ views an event's source. - ~g~ syncs new messages (not necessary if auto sync is enabled; see below). - ~r~ selects another room. - ~R~ shows the room list. - ~M-v~ or using the scroll wheel at the top of the buffer loads older messages. - Click an image to resize it to the window. - Double-click an image to show it in a new buffer at full size. ** Tips + You can customize settings in the ~ement~ group. - Set ~ement-auto-sync~ to sync new messages automatically. + Room buffers and the room-list buffer can be bookmarked in Emacs, i.e. using =C-x r m=. This is especially useful with [[https://github.com/alphapapa/burly.el][Burly]]: you can arrange an Emacs frame with several room buffers displayed at once, use =burly-bookmark-windows= to bookmark the layout, and then you can restore that layout and all of the room buffers by opening the bookmark, rather than having to manually arrange them every time you start Emacs or change the window configuration. *** Displaying symbols and emojis Emacs may not display certain symbols and emojis well by default. Based on [[https://emacs.stackexchange.com/questions/62049/override-the-default-font-for-emoji-characters][this question and answer]], you may find that the simplest way to fix this is to install an appropriate font, like [[https://www.google.com/get/noto/#emoji-zsye][Noto Emoji]], and then use this Elisp code: #+BEGIN_SRC elisp (setf use-default-font-for-symbols nil) (set-fontset-font t 'unicode "Noto Emoji" nil 'append) #+END_SRC * Changelog :PROPERTIES: :TOC: :depth 0 :END: ** 0.1-pre Yet to be released. * COMMENT Credits * Development Bug reports, feature requests, suggestions — /oh my/! * License GPLv3 # Local Variables: # eval: (require 'org-make-toc) # before-save-hook: org-make-toc # org-export-with-properties: () # org-export-with-title: t # End: