#+TITLE: Ement.el

#+PROPERTY: LOGGING nil

Export options.

#+OPTIONS: broken-links:t *:t num:1 toc:1

Info export options.

#+EXPORT_FILE_NAME: ement.texi #+TEXINFO_DIR_CATEGORY: Emacs #+TEXINFO_DIR_TITLE: Ement: (ement) #+TEXINFO_DIR_DESC: Matrix client for Emacs

Note: This readme works with the org-make-toc https://github.com/alphapapa/org-make-toc package, which automatically updates the table of contents.

#+HTML: <img src="images/logo-128px.png" align="right">

ELPA badge image.

[[https://elpa.gnu.org/packages/ement.html][https://elpa.gnu.org/packages/ement.svg]]

Ement.el is a [[http://www.matrix.org/][Matrix]] client for [[https://www.gnu.org/software/emacs/][GNU Emacs]]. It aims to be simple, fast, featureful, and reliable, while integrating naturally with Emacs.

Feel free to join us in the chat room: [[https://matrix.to/#/#ement.el:matrix.org][https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org]]

• Contents :noexport: :PROPERTIES: :TOC: :include siblings :END: :CONTENTS:

• [[#installation][Installation]]
• [[#usage][Usage]]
  • [[#bindings][Bindings]]
  • [[#tips][Tips]]
  • [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]]
• [[#changelog][Changelog]]
• [[#development][Development]] :END:

• Screenshots :noexport: :PROPERTIES: :ID: d818f690-5f22-4eb0-83e1-4d8ce16c9e5b :END:

The default formatting 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). Alternative, built-in styles include an Element-like one with usernames above groups of messages, as well as a classic, no-margins IRC style. Messages may be optionally displayed with unique colors for each user (with customizable contrast), making it easier to follow conversations. Timestamp headers are optionally displayed where a certain amount of time passes between events, as well as where the date changes.

[[images/ement-for-twim.png]]

/Two rooms shown in side-by-side buffers, showing inline images, reactions, date/time headings, room avatars, and messages colored by user (using the modus-vivendi Emacs theme)./

[[images/emacs-with-fully-read-line.png]]

/#emacs:libera.chat showing colored text from IRC users, replies with quoted parts, messages colored by user, addressed usernames colored by their user color, highlighted mentions, and the fully-read marker line (using the modus-vivendi Emacs theme)./

[[images/screenshot5.png]]

/Four rooms shown at once, with messages colored by user, in the default Emacs theme./

[[images/screenshot2.png]]

/A room at the top in the "Elemental" display style, with sender names displayed over groups of messages, and only self-messages in an alternate color. The lower window shows an earlier version of the rooms list./

[[images/reactions.png]]

/Reactions displayed as color emojis (may need [[#displaying-symbols-and-emojis][proper Emacs configuration]])./

• Installation :PROPERTIES: :TOC: :depth 0 :END:

** GNU ELPA

Ement.el is published in [[http://elpa.gnu.org/][GNU ELPA]] as [[https://elpa.gnu.org/packages/ement.html][ement]], so it may be installed in Emacs with the command M-x package-install RET ement RET. This is the recommended way to install Ement.el, as it will install the current stable release.

The latest development build may be installed from [[https://elpa.gnu.org/devel/ement.html][ELPA-devel]] or from Git (see below).

** GNU Guix

Ement.el is available in [[https://guix.gnu.org/][GNU Guix]] as [[https://packages.guix.gnu.org/packages/emacs-ement/][emacs-ement]].

** Debian, Ubuntu

Ement.el is available in [[https://packages.debian.org/elpa-ement][Debian as elpa-ement]] and in [[https://packages.ubuntu.com/search?suite=default&section=all&arch=any&keywords=elpa-ement&searchon=names][Ubuntu as elpa-ement]].

** Nix

Ement.el is available in [[https://nixos.org/][NixOS]] as [[https://search.nixos.org/packages?channel=23.05&show=emacsPackages.ement&from=0&size=50&sort=relevance&type=packages&query=ement][emacsPackages.ement]].

** Other distributions

Ement.el is also available in some other distributions. See [[https://repology.org/project/emacs:ement/related][Repology]] for details.

** Git master

The master branch of the Git repository is intended to be usable at all times; only minor bugs are expected to be found in it before a new stable release is made.

To install, it is recommended to use [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this (using [[https://github.com/alphapapa/unpackaged.el#upgrade-a-quelpa-use-package-forms-package][this helpful command]] for upgrading versions):

#+BEGIN_SRC elisp ;; Install and load `quelpa-use-package'. (package-install 'quelpa-use-package) (require 'quelpa-use-package)

;; Install Ement. (use-package ement :quelpa (ement :fetcher github :repo "alphapapa/ement.el")) #+END_SRC

One might also use systems like [[https://github.com/progfolio/elpaca][Elpaca]] or [[https://github.com/radian-software/straight.el][Straight]] (which is also used by [[https://github.com/doomemacs/doomemacs][DOOM]]), but the author cannot offer support for them.

** Manual

Ement.el is intended to be installed with Emacs's package system, which will ensure that the required autoloads are generated, etc. If you choose to install it manually, you're on your own.

• Usage :PROPERTIES: :TOC: :include descendants :depth 1 :END: :CONTENTS:

• [[#bindings][Bindings]]
• [[#tips][Tips]]
• [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]] :END:

1. Call command ement-connect to connect. Multiple sessions are supported: call the command again with a C-u universal prefix to connect to another account.
2. Wait for initial sync to complete (which can take a few moments--initial sync JSON responses can be large).
3. Use these commands (room-related commands may be called with universal prefix to prompt for the room):
   • ement-list-rooms to view the list of joined rooms.
   • ement-view-room to view a room's buffer, selected with completion.
   • ement-create-room to create a new room.
   • ement-create-space to create a space.
   • ement-invite-user to invite a user to a room.
   • ement-join-room to join a room.
   • ement-leave-room to leave a room.
   • ement-forget-room to forget a room.
   • ement-tag-room to toggle a tag on a room (including favorite/low-priority status).
   • ement-list-members to list members in a room.
   • ement-send-direct-message to send a direct message to a user (in an existing direct room, or creating a new one automatically).
   • ement-room-edit-message to edit a message at point.
   • ement-room-send-file to send a file.
   • ement-room-send-image to send an image.
   • ement-room-set-topic to set a room's topic.
   • ement-room-occur to search in a room's known events.
   • ement-room-override-name to override a room's display name.
   • ement-ignore-user to ignore a user (or with interactive prefix, un-ignore).
   • ement-room-set-message-format to set a room's message format buffer-locally.
   • ement-room-toggle-space to toggle a room's membership in a space (a way to group rooms in Matrix).
   • ement-directory to view a room directory.
   • ement-directory-search to search a room directory.
4. Use these special buffers to see events from multiple rooms (you can also reply to messages from these buffers!):
   • See all new events that mention you in the =Ement Mentions= buffer.
   • See all new events in rooms that have open buffers in the =Ement Notifications= buffer.

** Bindings

These bindings are common to all of the following buffer types:

• Switch to a room buffer: M-g M-r
• Switch to the room list buffer: M-g M-l
• Switch to the mentions buffer: M-g M-m
• Switch to the notifications buffer: M-g M-n

*** Room buffers

Note that if global minor mode ement-room-self-insert-mode is enabled (by default it is disabled), typing any of the common printable ascii characters (such as letters) in a room buffer will start a new message, and most of the following bindings are instead accessed via a prefix key. See the minor mode docstring for details. (The ? binding is an exception; by default it opens the command menu regardless of this minor mode.)

• Show command menu: ?

[[images/transient.png]]

Movement

• Next event: n
• Previous event: p
• End of buffer: N
• Scroll up and mark read: SPC
• Scroll down: S-SPC
• Jump to fully-read marker: M-g M-p
• Move read markers to point: m
• Load older messages: at top of buffer, scroll contents up (i.e. S-SPC, M-v or mwheel-scroll)

Switching

• List rooms: M-g M-l
• Switch to other room: M-g M-r
• Switch to mentions buffer: M-g M-m
• Switch to notifications buffer: M-g M-n
• Quit window: q

Messages

• Write message: RET
• Compose message in buffer: M-RET (while writing in minibuffer: C-c '‍). Customize the option ement-room-compose-method to make RET and the other message bindings use a compose buffer by default. Use command ement-room-compose-org to activate Org mode in the compose buffer.
• Write reply to event at point: S-<return>
• Edit message: <insert>
• Delete message: C-k
• Send reaction to event at point, or send same reaction at point: s r
• Send emote: s e
• Send file: s f
• Send image: s i
• View event source: v
• Complete members and rooms at point: C-M-i (standard completion-at-point command). (Type an @ prefix for a member mention, a # prefix for a room alias, or a ! prefix for a room ID.)

Images

• Toggle scale of image (between fit-to-window and thumbnail): mouse-1
• Show image in new buffer at full size: double-mouse-1

Users

• Send direct message: u RET
• Invite user: u i
• Ignore user: u I

Room

• Occur search in room: M-s o
• List members: r m
• Set topic: r t
• Set message format: r f
• Set notification rules: r n
• Override display name: r N
• Tag/untag room: r T

Room membership

• Create room: R c
• Join room: R j
• Leave room: R l
• Forget room: R F
• Toggle room's spaces: R s

Other

• Sync new messages (not necessary if auto sync is enabled; with prefix to force new sync): g

*** Room list buffer

• Show buffer of room at point: RET

• Show buffer of next unread room: SPC

• Move between room names: TAB / <backtab>

• Kill room's buffer: k

• Toggle room's membership in a space: s

*** Directory buffers

• View/join a room: RET / mouse-1
• Load next batch of rooms: +

*** Mentions/notifications buffers

• Move between events: TAB / <backtab>
• Go to event at point in its room buffer: RET
• Write reply to event at point (shows the event in its room while writing): S-<return>

** Tips

TODO: Show sending messages in Org format.

• Desktop notifications are enabled by default for events that mention the local user. They can also be shown for all events in rooms with open buffers.
• Send messages in Org mode format by customizing the option ement-room-send-message-filter (which enables Org format by default), or by calling ement-room-compose-org in a compose buffer (which enables it for a single message). Then Org-formatted messages are automatically converted and sent as HTML-formatted messages (with the Org syntax as the plain-text fallback). You can send syntax such as:
  • Bold, italic, underline, strikethrough
  • Links
  • Tables
  • Source blocks (including results with :exports both)
  • Footnotes (okay, that might be pushing it, but you can!)
  • And, generally, anything that Org can export to HTML
  • Note that the default org-export-preserve-breaks value causes singular line breaks to be exported as spaces. To preserve the line breaks, indentation, and blank lines in a region, but otherwise use normal formatting, you can use the verse block type. Refer to (info "(org) Paragraphs") and (info "(org) Structure Templates") for details.
• Starting in the room list buffer, by pressing SPC repeatedly, you can cycle through and read all rooms with unread buffers. (If a room doesn't have a buffer, it will not be included.)
• 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.
• Images and other files can be uploaded to rooms using drag-and-drop.
• Mention members by typing a @ followed by their displayname or Matrix ID. (Members' names and rooms' aliases/IDs may be completed with completion-at-point commands.)
• Customize ement-room-use-variable-pitch to render messages using proportional fonts.
• You can customize settings in the ement group.
  • Note: setq should not be used for certain options, because it will not call the associated setter function. Users who have an aversion to the customization system may experience problems.

*** 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

** Encrypted room support through Pantalaimon

Ement.el doesn't support encrypted rooms natively, but it can be used transparently with the E2EE-aware reverse proxy daemon [[https://github.com/matrix-org/pantalaimon/][Pantalaimon]]. After configuring it according to its documentation, call ement-connect with the appropriate hostname and port, like:

#+BEGIN_SRC elisp (ement-connect :uri-prefix "http://localhost:8009") #+END_SRC

• Changelog :PROPERTIES: :TOC: :depth 0 :END:

** 0.16-pre

Changes

• Option ement-room-coalesce-events may now be set to (and defaults to) a maximum number of events to coalesce together. (This avoids potential performance problems in rare cases. See [[https://github.com/alphapapa/ement.el/issues/247][#247]]. Thanks to [[https://github.com/viiru-][Arto Jantunen]] for reporting and [[https://github.com/sergiodj][Sergio Durigan Junior]] for testing.)

Fixes

• Replies to edited messages are correctly sent to the original event (whereas previously they were sent to the edit, which caused reactions to not be shown). ([[https://github.com/alphapapa/ement.el/issues/230][#230]], [[https://github.com/alphapapa/ement.el/issues/277][#277]]. Thanks to [[https://github.com/phil-s][Phil Sainty]] for suggesting, and to [[https://github.com/dionisos2][dionisos]] for reporting.)

** 0.15.1

Fixes

• Handle unnamed rooms in ement-directory list. (See [[https://github.com/alphapapa/ement.el/issues/248][#248]].