diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 87eab54..68e92ac 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -11,10 +11,13 @@ - [Browsing](./rooms/browsing.md) - [Members](./rooms/members.md) - [Management](./rooms/management.md) + - [Admin](./rooms/admin.md) - [Messages](./messages/README.md) - [Screen Navigation](./layout/README.md) - [Window Management](./layout/windows.md) - [Tab Management](./layout/tabs.md) -- [Command Reference](./commands.md) -- [Keybinding Reference](./keybindings.md) - [Development](./development.md) + +[Command Reference](./commands.md) +[Keybinding Reference](./keybindings.md) +[Terminal Comparisons](./terminals.md) diff --git a/src/commands.md b/src/commands.md index 470e8bf..9bc5bc8 100644 --- a/src/commands.md +++ b/src/commands.md @@ -2,39 +2,60 @@ ## iamb commands -| Command | Aliases | Help | -| ------------------- | ------------------------------------- | ----------------------------------------- | -| `:chats` | | See [Browsing Rooms And DMs Together] | -| `:create` | | See [Room Creation] | -| `:dms` | | See [Browsing Direct Messages] | -| `:download` | | See [Downloading Attachments] | -| `:edit` | | See [Editing Messages] | -| `:editor` | | See [Sending] | -| `:invite accept` | | See [Room Invitations] | -| `:invite reject` | | See [Room Invitations] | -| `:invite send` | | See [Room Invitations] | -| `:join` | | See [Joining And Leaving Rooms] | -| `:keys export` | | See [Exporting / Importing Keys] | -| `:keys import` | | See [Exporting / Importing Keys] | -| `:leave` | | See [Joining And Leaving Rooms] | -| `:logout` | | Log out of the client. | -| `:members` | | See [Viewing Room/Space Members] | -| `:open` | | See [Downloading Attachments] and [Opening Links] | -| `:react` | | See [Reacting To A Message] | -| `:redact` | | See [Redacting A Message] | -| `:reply` | | See [Replying To A Message] | -| `:rooms` | | See [Browsing Rooms] | -| `:room name set` | | See [Setting Room Properties] | -| `:room name unset` | | See [Setting Room Properties] | -| `:room tag set` | | See [Setting Room Tags] | -| `:room tag unset` | | See [Setting Room Tags] | -| `:room topic set` | | See [Setting Room Properties] | -| `:room topic unset` | | See [Setting Room Properties] | -| `:spaces` | | See [Browsing Spaces] | -| `:unreact` | | See [Reacting To A Message] | -| `:upload` | | See [Sending] | -| `:verify` | | See [Verification] | -| `:welcome` | | Shows the startup Welcome window | +| Command | Aliases | Help | +| ------------------- | ------------------------------------- | ----------------------------------------- | +| `:chats` | | See [Browsing Rooms And DMs Together] | +| `:create` | | See [Room Creation] | +| `:dms` | | See [Browsing Direct Messages] | +| `:download` | | See [Downloading Attachments] | +| `:edit` | | See [Editing Messages] | +| `:editor` | | See [Sending] | +| `:invite accept` | | See [Room Invitations] | +| `:invite reject` | | See [Room Invitations] | +| `:invite send` | | See [Room Invitations] | +| `:join` | | See [Joining And Leaving Rooms] | +| `:keys export` | | See [Exporting / Importing Keys] | +| `:keys import` | | See [Exporting / Importing Keys] | +| `:leave` | | See [Joining And Leaving Rooms] | +| `:logout` | | Log out of the client. | +| `:members` | | See [Viewing Room/Space Members] | +| `:open` | | See [Downloading Attachments] and [Opening Links] | +| `:react` | | See [Reacting To A Message] | +| `:redact` | | See [Redacting A Message] | +| `:reply` | | See [Replying To A Message] | +| `:rooms` | | See [Browsing Rooms] | +| `:room alias set` | | See [Setting Room Aliases] | +| `:room alias show` | | See [Setting Room Aliases] | +| `:room alias unset` | | See [Setting Room Aliases] | +| `:room ban` | | See [Managing Room Membership] | +| `:room canon set` | `:room canonicalalias set` | See [Setting Room Aliases] | +| `:room canon show` | `:room canonicalalias show` | See [Setting Room Aliases] | +| `:room canon unset` | `:room canonicalalias unset` | See [Setting Room Aliases] | +| `:room dm unset` | | See [Marking Direct Rooms] | +| `:room dm set` | | See [Marking Direct Rooms] | +| `:room dm unset` | | See [Marking Direct Rooms] | +| `:room history set` | | See [Setting History Visibility] | +| `:room history unset` | | See [Setting History Visibility] | +| `:room kick` | | See [Managing Room Membership] | +| `:room name set` | | See [Setting Room Properties] | +| `:room name show` | | See [Setting Room Properties] | +| `:room name unset` | | See [Setting Room Properties] | +| `:room notify set` | | See [Configuring Room Notifications] | +| `:room notify show` | | See [Configuring Room Notifications] | +| `:room notify unset` | | See [Configuring Room Notifications] | +| `:room tag set` | | See [Setting Room Tags] | +| `:room tag unset` | | See [Setting Room Tags] | +| `:room topic set` | | See [Setting Room Properties] | +| `:room topic show` | | See [Setting Room Properties] | +| `:room topic unset` | | See [Setting Room Properties] | +| `:room unban` | | See [Managing Room Membership] | +| `:spaces` | | See [Browsing Spaces] | +| `:unreact` | | See [Reacting To A Message] | +| `:unreads` | | See [Browsing Unreads] | +| `:unreads clear` | | See [Browsing Unreads] | +| `:upload` | | See [Sending] | +| `:verify` | | See [Verification] | +| `:welcome` | | Shows the startup Welcome window | ## Vim commands @@ -80,11 +101,15 @@ table th:nth-of-type(3) { [Browsing Rooms]: ./rooms/browsing.md#browsing-rooms [Browsing Rooms And DMs Together]: ./rooms/browsing.md#browsing-rooms-and-dms-together [Browsing Spaces]: ./rooms/browsing.md#browsing-spaces +[Browsing Unreads]: ./rooms/browsing.md#browsing-unreads [Closing Tabs]: ./layout/tabs.md#closing-tabs [Closing Windows]: ./layout/tabs.md#closing-windows +[Configuring Room Notifications]: ./rooms/management.md#configuring-room-notifications [Downloading Attachments]: ./messages/#downloading-attachments [Editing Messages]: ./messages/#editing-messages [Exporting / Importing Keys]: ./e2ee/keys.md#exporting-importing-keys +[Managing Room Membership]: ./rooms/admin.md#managing-room-membership +[Marking Direct Rooms]: ./rooms/management.md#marking-direct-rooms [Opening Links]: ./messages/#opening-links [Opening Tabs]: ./layout/tabs.md#opening-tabs [Opening Windows]: ./layout/tabs.md#opening-windows @@ -97,7 +122,9 @@ table th:nth-of-type(3) { [Room Invitations]: ./rooms/management.md#room-invitations [Joining And Leaving Rooms]: ./rooms/#joining-and-leaving-rooms [Sending]: ./messages/#sending -[Setting Room Properties]: ./rooms/management.md#setting-room-properties +[Setting History Visibility]: ./rooms/admin.md#setting-history-visibility +[Setting Room Aliases]: ./rooms/admin.md#setting-room-aliases +[Setting Room Properties]: ./rooms/admin.md#setting-room-properties [Setting Room Tags]: ./rooms/management.md#setting-room-tags [Switching Tabs]: ./layout/tabs.md#switching-tabs [Verification]: ./e2ee/verify.md diff --git a/src/configure.md b/src/configure.md index 243b4f2..2553e29 100644 --- a/src/configure.md +++ b/src/configure.md @@ -87,6 +87,7 @@ url = "https://example.com" | Name | Default | Description | | ---------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `default_room` | | A default room name or username to open at startup, in place of showing the welcome screen. | +| `external_edit_file_suffix` | `.md` | The file suffix to use when creating temporary files with message contents for `:edit`. (Usually you want the default `.md` for syntax highlighting.) | | `image_preview` | (unset) | Configures displaying image attachments for terminals that support previewing images. See [Image Previews](#image-previews) below. | | `log_level` | `"info"` | Configures the minimum log level. Valid values are `"trace"`, `"debug"`, `"info"`, `"warn"` or `"error"`. | | `message_user_color` | `false` | Whether to color entire messages using the same color used for the sender's username and display name. | @@ -167,6 +168,9 @@ you can put the following in your configuration: enabled = true ``` +See [Configuring Room Notifications] for how to adjust the per-room +notification level. + #### Notification fields | Name | Default | Description | @@ -380,6 +384,7 @@ table th:nth-of-type(3) { [dirs::config_dir]: https://docs.rs/dirs/latest/dirs/fn.config_dir.html [`${dirs::data_dir}`]: https://docs.rs/dirs/latest/dirs/fn.data_dir.html [`${dirs::download_dir}`]: https://docs.rs/dirs/latest/dirs/fn.download_dir.html +[Configuring Room Notifications]: ./rooms/management.md#configuring-room-notifications [iTerm2]: https://iterm2.com/ [Kitty]: https://sw.kovidgoyal.net/kitty/ [well_known_entry]: https://spec.matrix.org/latest/client-server-api/#getwell-knownmatrixclient diff --git a/src/install.md b/src/install.md index da6fdb8..7d447c4 100644 --- a/src/install.md +++ b/src/install.md @@ -57,11 +57,11 @@ to install something besides the most recent release (e.g. `main` or `v0.0.8`). ### openSUSE Tumbleweed -On openSUSE Tumbleweed a [package][openSUSE] is available from openSUSE Build -Service (OBS). You can install it using OBS Package Installer: +On openSUSE Tumbleweed a [package][openSUSE] is available from the official +repositories. To install it simply run: ``` -opi iamb +zypper install iamb ``` ### Snap @@ -74,7 +74,8 @@ snap install iamb ## GitHub Releases -You can find binaries built for x86\_64 Linux from the [Releases] page on GitHub. +You can find `.deb`, `.rpm` and binaries built for `x86_64` and `aarch64` Linux +from the [Releases] page on GitHub. ## From crates.io @@ -98,16 +99,29 @@ $ git clone https://github.com/ulyssa/iamb.git $ cd iamb $ cargo build --release $ ./target/release/iamb --version -iamb 0.0.9 (82645c8) +iamb 0.0.10 (2e6376f) +``` + +If you would like to build `.deb` or `.rpm` packages from the repository, +you can do so using [cargo-deb] and [cargo-generate-rpm] respectively. For +example: + +``` +$ cargo deb + Compiling iamb v0.0.10 (/home/ufsm/src/iamb) + Finished `release` profile [optimized] target(s) in 2m 25s +/home/ufsm/src/iamb/target/debian/iamb_0.0.10-1_amd64.deb ``` [AUR helper]: https://wiki.archlinux.org/title/AUR_helpers +[cargo-deb]: https://crates.io/crates/cargo-deb +[cargo-generate-rpm]: https://crates.io/crates/cargo-generate-rpm [crates.io]: https://crates.io/crates/iamb [enabled flakes]: https://nixos.wiki/wiki/Flakes#Enable_flakes [GitHub]: https://github.com/ulyssa/iamb [homebrew]: https://formulae.brew.sh/formula/iamb#default [install-snap]: https://snapcraft.io/docs/installing-snapd -[openSUSE]: https://build.opensuse.org/package/show/home%3Asmolsheep/iamb +[openSUSE]: https://build.opensuse.org/package/show/openSUSE:Factory/iamb [pkgsrc]: https://pkgsrc.smartos.org/ [Releases]: https://github.com/ulyssa/iamb/releases/ [repology]: https://repology.org/project/iamb/versions diff --git a/src/messages/README.md b/src/messages/README.md index 75ce722..829be70 100644 --- a/src/messages/README.md +++ b/src/messages/README.md @@ -41,6 +41,25 @@ the PRIMARY selection), then you could paste it with `"*p`. > text editor, you can use the `:editor` command to launch your configured > `$EDITOR`. +## Message Slash Commands + +You can prefix a message with several different slash commands to change the +message type or format: + +- `/me` to send an emote message +- `/html`/`/h` to send an HTML body +- `/plain`/`/p` to send a plaintext body + +These slash commands won't appear with any special effects in __iamb__, but do +produce effects in other clients: + +- `/confetti` to add confetti effects +- `/fireworks` to add fireworks effects +- `/hearts` to add floating hearts +- `/snowfall` to add snowfall effects +- `/rainfall` to add rainfall effects +- `/spaceinvaders` to add falling [Space Invaders] + ## Message Scrollback You can scroll through messages from the message bar using the following keys: @@ -106,6 +125,16 @@ instead. For example, we could have also written the above as: :react heart ``` +If the argument isn't the shortcode name of an Emoji, then you will be prompted +for whether you want to react with the literal text. You can force literal text +by adding a `!` to the argument. For example, none of these will appear as Emoji: + +``` +:react! heart +:react! laughing +:react! "hello world" +``` + If you want to remove a reaction, you can do so with the `:unreact` command. By default, this will remove all your reactions from the specified message, but you can give a name if you've made any that you want to keep: @@ -154,3 +183,4 @@ browser by typing its assigned character. [GitHub Emoji shortcodes]: https://github.com/ikatyang/emoji-cheat-sheet/blob/master/README.md [open_command]: ./configure.md#Settings +[Space Invaders]: https://en.wikipedia.org/wiki/Space_Invaders diff --git a/src/rooms/admin.md b/src/rooms/admin.md new file mode 100644 index 0000000..1662e02 --- /dev/null +++ b/src/rooms/admin.md @@ -0,0 +1,111 @@ +# Administration + +If you have the appropriate power level in a room, then you can change room +settings and membership as described throughout this page. + +## Managing Room Membership + +Both bot spam and aggressive users are an unfortunately reality, and you may +sometimes find yourself needing to get rid of users in a room. You can ban +a user with: + +``` +:room ban @user:example.com +``` + +If you would like to unban someone, you can do: + +``` +:room unban @user:example.com +``` + +And if you just need to kick them out of the room without banning them (for +example, when dealing with a user from a homeserver that no longer exists and +is causing perpetual errors in federation), then you can do: + +``` +:room kick @user:example.com +``` + +If you find yourself managing a large room and needing to often ban users, you +may want to look at something like [mjolnir] to help you manage a ban list. + +## Setting Room Aliases + +You can add a new alias to a room with: + +``` +:room alias set #alias:example.com +``` + +And remove an alias with: + +``` +:room alias unset #alias:example.com +``` + +If you want to add a canonical alias or promote an existing one to be +canonical, then you can use: + +``` +:room canon set #alias:example.com +``` + +If there was an existing canonical alias, then it will be demoted to a regular +alternative room alias. + +If you want a room alias to no longer be canonical, then you can make it an +alternative alias with: + +``` +:room canon unset #alias:example.com +``` + +> If you don't know what the room's current canonical or alternative aliases +> are, you can see them with: +> +> ``` +> :room canon show +> :room alias show +> ``` + +## Setting Room Properties + +You can set the description of the currently focused room using its `set` command: + +``` +:room topic set "This is the new room topic" +``` + +Similarly, if you need to change the room's name: + +``` +:room name set "Watercooler Discussion" +``` + +If you want to remove the topic or name, you can use `:room topic unset` or +`:room name unset`. + +## Setting History Visibility + +Depending on what your rooms are used for, you may want to configure different +visibility settings for the room history. Your options include: + +- `invited`, which configures the room to allow people to see history from the point they were invited onwards. +- `joined`, which configures the room to allow people to see history from the point they actually join the room. +- `shared`, which configures the room to allow people to see all history once they are joined, including messages from before they joined. +- `world`/`world_readable` which configures the room to allow anyone to see the room history regardless of whether they are joined and in it. + +You can then set it with: + +``` +:room history set [invited|joined|shared|world] +``` + +You can see the current setting with: + +``` +:room history show +``` + +[mjolnir]: https://github.com/matrix-org/mjolnir diff --git a/src/rooms/browsing.md b/src/rooms/browsing.md index 232cb1e..b6cd08b 100644 --- a/src/rooms/browsing.md +++ b/src/rooms/browsing.md @@ -13,6 +13,16 @@ You can switch to a list of direct messages using the `:dms` command. You can switch to a list of both joined rooms and direct messages using the `:chats` command. +## Browsing Unreads + +You can view a list of rooms and direct messages with unread messages +using the `:unreads` command. If you don't want to visit all of them +to read them each individually, you can mark them all as read with: + +``` +:unreads clear +``` + ## Browsing Spaces You can switch to a list of joined spaces using the `:spaces` command. diff --git a/src/rooms/management.md b/src/rooms/management.md index 2fc3c69..bfbbf7d 100644 --- a/src/rooms/management.md +++ b/src/rooms/management.md @@ -34,23 +34,23 @@ you can open it up, focus the window and run: - `:invite accept` to accept the invitation and join the room - `:invite reject` to reject the invitation -## Setting Room Properties +## Marking Direct Rooms -You can set the description of the currently focused room using the `:set` command: +Matrix keeps a list of direct message rooms in account data on the server. If +you have a room that you want to appear under `:dms` and it's not currently +there, you can add the currently focused room to your account's list of direct +messages with: ``` -:room topic set "This is the new room topic" +:room dm set ``` -Similarly, if you need to change the room's name: +Similarly, if you *don't* want it to be a DM: ``` -:room name set "Watercooler Discussion" +:room dm unset ``` -If you want to remove the topic or name, you can use `:room topic unset` or -`:room name unset`. - ## Setting Room Tags Matrix rooms can be tagged to help with sorting them. Several special tags that @@ -85,3 +85,32 @@ could do: Note that user tags are not shown by all clients, so while they will appear in __iamb__, you won't necessarily see them elsewhere. + +## Configuring Room Notifications + +If you've [enabled notifications], you may want to reconfigure some rooms to +not notify you as much. The different notification levels are: + +- `mute`, which disables notifications for this room. +- `keywords`/`mentions`, which only shows notifications for mentions of the user and configured keywords. +- `all`, which shows notifications for every message to this room. + +You can update a room with: + +``` +:room notify set [mute|keywords|mentions|all] +``` + +You can remove the per-room override with: + +``` +:room notify unset +``` + +And see the currently configured value for the room with: + +``` +:room notify show +``` + +[enabled notifications]: ../configure.md#notifications diff --git a/src/terminals.md b/src/terminals.md new file mode 100644 index 0000000..d4f558c --- /dev/null +++ b/src/terminals.md @@ -0,0 +1,48 @@ +# Terminal Comparisons + +While you should be able to use __iamb__ in any terminal with reasonable UTF-8 +support, if you want to be able to see images in room history or use keypresses +like ``, you might find this table useful: + +| Terminal | Operating Systems | Images | Extended Keypresses | +| ----------------- | ----------------------------------------------- | -------------------------- | ------------------- | +| [alacritty] | FreeBSD, Linux, macOS, NetBSD, OpenBSD, Windows | N | Y[^note-kitty-keys] | +| [ConEmu] | Windows | N[^note-conemu] | Y[^note-win-keys] | +| [foot] | FreeBSD, Linux, OpenBSD | Y[^note-sixel] | Y[^note-kitty-keys] | +| [gnome-terminal] | FreeBSD, Linux, NetBSD, OpenBSD | N | N[^note-gnome-term] | +| [iTerm2] | macOS | Y[^note-iterm2-img] | N | +| [kitty] | FreeBSD, Linux, macOS, NetBSD, OpenBSD | Y[^note-kitty-img-new] | Y[^note-kitty-keys] | +| [konsole] | FreeBSD, Linux, NetBSD, OpenBSD | Y[^note-sixel] | N[^note-konsole] | +| [mlterm] | FreeBSD, Linux, NetBSD, OpenBSD | Y[^note-sixel] | N | +| [rio] | FreeBSD, Linux, macOS, Windows | Y[^note-iterm2-img] | Y[^note-kitty-keys] | +| [wezterm] | FreeBSD, Linux, macOS, Windows | Y[^note-iterm2-img] | Y[^note-kitty-keys] | +| [Windows Terminal]| Windows | Y[^note-sixel] | Y[^note-win-keys] | + +[^note-kitty-keys]: Uses Kitty enhanced keyboard protocol + +[^note-conemu]: See [ConEmu tracking issue](https://github.com/Maximus5/ConEmu/issues/807) + +[^note-win-keys]: Uses Windows APIs + +[^note-sixel]: Uses [sixel] image protocol + +[^note-gnome-term]: See [vte tracking issue](https://gitlab.gnome.org/GNOME/vte/-/issues/2601) + +[^note-iterm2-img]: Uses iTerm2 inlines images protocol + +[^note-kitty-img-new]: Uses the [new Kitty image protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/#unicode-placeholders) + +[^note-konsole]: See [konsole tracking issue](https://bugs.kde.org/show_bug.cgi?id=435975) + +[alacritty]: https://alacritty.org/ +[ConEmu]: https://conemu.github.io/ +[foot]: https://codeberg.org/dnkl/foot +[gnome-terminal]: https://help.gnome.org/users/gnome-terminal/stable/ +[iTerm2]: https://iterm2.com/ +[kitty]: https://sw.kovidgoyal.net/kitty/ +[konsole]: https://konsole.kde.org/ +[mlterm]: https://mlterm.sourceforge.net/ +[rio]: https://raphamorim.io/rio/ +[sixel]: https://www.arewesixelyet.com/ +[wezterm]: https://wezfurlong.org/wezterm/index.html +[Windows Terminal]: https://apps.microsoft.com/detail/9n0dx20hk701