From 6600685dd55ab2a374896526503f60a4f3c07b82 Mon Sep 17 00:00:00 2001 From: Ulyssa Date: Tue, 26 Mar 2024 08:55:22 -0700 Subject: [PATCH] Update manual pages to use mdoc(7) and list commands (#230) --- .gitignore | 1 - Cargo.lock | 42 +--- Cargo.toml | 5 +- PACKAGING.md | 11 + build.rs | 20 -- config.example.toml | 14 +- docs/iamb.1 | 196 ++++++++++++++++ docs/iamb.1.md | 29 --- docs/iamb.5 | 555 ++++++++++++++++++++++++++++++++++++++++++++ docs/iamb.5.md | 171 -------------- 10 files changed, 778 insertions(+), 266 deletions(-) create mode 100644 docs/iamb.1 delete mode 100644 docs/iamb.1.md create mode 100644 docs/iamb.5 delete mode 100644 docs/iamb.5.md diff --git a/.gitignore b/.gitignore index 7af713a..a20db45 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ /target /result /TODO -/docs/iamb.[15] .direnv diff --git a/Cargo.lock b/Cargo.lock index 6279e0f..7df752a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1110,12 +1110,6 @@ version = "0.4.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d95203a6a50906215a502507c0f879a0ce7ff205a6111e2db2a5ef8e4bb92e43" -[[package]] -name = "deunicode" -version = "1.4.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "890d779e1bc371e4fa7727ef6d29a9346be20ddfe40cd8c744cd083ce0640b15" - [[package]] name = "diff" version = "0.1.13" @@ -1704,15 +1698,6 @@ dependencies = [ "windows-targets 0.48.5", ] -[[package]] -name = "getopts" -version = "0.2.21" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "14dbbfd5c71d70241ecf9e6f13737f7b5ce823821063188d7e46c41d371eebd5" -dependencies = [ - "unicode-width", -] - [[package]] name = "getrandom" version = "0.2.12" @@ -1966,7 +1951,7 @@ dependencies = [ [[package]] name = "iamb" -version = "0.0.9-alpha.1" +version = "0.0.9" dependencies = [ "arboard", "bitflags 2.4.2", @@ -1983,7 +1968,6 @@ dependencies = [ "image", "lazy_static 1.4.0", "libc", - "mandown", "markup5ever_rcdom", "matrix-sdk", "mime", @@ -2470,16 +2454,6 @@ dependencies = [ "libc", ] -[[package]] -name = "mandown" -version = "0.1.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "12243a468e9660b178540f73c43bdc544d64bd3cde749de0bd851e0dbacfd683" -dependencies = [ - "deunicode 1.4.0", - "pulldown-cmark", -] - [[package]] name = "maplit" version = "1.0.2" @@ -3480,18 +3454,6 @@ dependencies = [ "syn 2.0.52", ] -[[package]] -name = "pulldown-cmark" -version = "0.9.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "77a1a2f1f0a7ecff9c31abbe177637be0e97a0aef46cf8738ece09327985d998" -dependencies = [ - "bitflags 1.3.2", - "getopts", - "memchr", - "unicase", -] - [[package]] name = "qoi" version = "0.4.1" @@ -4317,7 +4279,7 @@ version = "0.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b3bc762e6a4b6c6fcaade73e77f9ebc6991b676f88bb2358bddb56560f073373" dependencies = [ - "deunicode 0.4.4", + "deunicode", ] [[package]] diff --git a/Cargo.toml b/Cargo.toml index 5efbfed..8c54f91 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "iamb" -version = "0.0.9-alpha.1" +version = "0.0.9" edition = "2018" authors = ["Ulyssa "] repository = "https://github.com/ulyssa/iamb" @@ -20,9 +20,6 @@ bundled = ["matrix-sdk/bundled-sqlite", "rustls-tls"] native-tls = ["matrix-sdk/native-tls"] rustls-tls = ["matrix-sdk/rustls-tls"] -[build-dependencies] -mandown = "0.1.3" - [build-dependencies.vergen] version = "8" default-features = false diff --git a/PACKAGING.md b/PACKAGING.md index 464be4d..eb42980 100644 --- a/PACKAGING.md +++ b/PACKAGING.md @@ -23,5 +23,16 @@ enable it when building: Note that this [can fail][ring-lto] in some build environments if both Clang and GCC are present. +## Documentation + +In addition to the compiled binary, there are other files in the repo that +you'll want to install as part of a package: + +| Repository Path | Installed Path (may vary per OS) | +| -------------------- | ----------------------------------- | +| /config.example.toml | /usr/share/iamb/config.example.toml | +| /docs/iamb.1 | /usr/share/man/man1/iamb.1 | +| /docs/iamb.5 | /usr/share/man/man5/iamb.5 | + [ring-lto]: https://github.com/briansmith/ring/issues/1444 [rustls]: https://crates.io/crates/rustls diff --git a/build.rs b/build.rs index afc3aa3..69631a0 100644 --- a/build.rs +++ b/build.rs @@ -1,29 +1,9 @@ use std::error::Error; -use std::fs; -use std::iter::FromIterator; -use std::path::PathBuf; -use mandown::convert; use vergen::EmitBuilder; -const IAMB_1_MD: &str = include_str!("docs/iamb.1.md"); -const IAMB_5_MD: &str = include_str!("docs/iamb.5.md"); - fn main() -> Result<(), Box> { EmitBuilder::builder().git_sha(true).emit()?; - // Build the manual pages. - println!("cargo:rerun-if-changed=docs/iamb.1.md"); - println!("cargo:rerun-if-changed=docs/iamb.5.md"); - - let iamb_1 = convert(IAMB_1_MD, "IAMB", 1); - let iamb_5 = convert(IAMB_5_MD, "IAMB", 5); - - let out_dir = std::env::var("OUT_DIR"); - let out_dir = out_dir.as_deref().unwrap_or("docs"); - - fs::write(PathBuf::from_iter([out_dir, "iamb.1"]), iamb_1.as_bytes())?; - fs::write(PathBuf::from_iter([out_dir, "iamb.5"]), iamb_5.as_bytes())?; - Ok(()) } diff --git a/config.example.toml b/config.example.toml index 5e47176..598b0ff 100644 --- a/config.example.toml +++ b/config.example.toml @@ -31,7 +31,19 @@ members = ["power", "id"] "@user:matrix.org" = { "name" = "John Doe", "color" = "magenta" } [layout] -style = "restore" +style = "config" + +[[layout.tabs]] +window = "iamb://dms" + +[[layout.tabs]] +window = "iamb://rooms" + +[[layout.tabs]] +split = [ + { "window" = "#iamb-users:0x.badd.cafe" }, + { "window" = "#iamb-dev:0x.badd.cafe" } +] [macros.insert] "jj" = "" diff --git a/docs/iamb.1 b/docs/iamb.1 new file mode 100644 index 0000000..cd88e71 --- /dev/null +++ b/docs/iamb.1 @@ -0,0 +1,196 @@ +.\" iamb(1) manual page +.\" +.\" This manual page is written using the mdoc(7) macros. For more +.\" information, see . +.\" +.\" You can preview this file with: +.\" $ man ./docs/iamb.1 +.Dd Mar 24, 2024 +.Dt IAMB 1 +.Os +.Sh NAME +.Nm iamb +.Nd a terminal-based client for Matrix for the Vim addict +.Sh SYNOPSIS +.Nm +.Op Fl hV +.Op Fl P Ar profile +.Op Fl C Ar dir +.Sh DESCRIPTION +.Nm +is a client for the Matrix communication protocol. +It provides a terminal user interface with familiar Vim keybindings, and +includes support for multiple profiles, threads, spaces, notifications, +reactions, custom keybindings, and more. +.Pp +This manual page includes a quick rundown of the available commands in +.Nm . +For example usage and a full description of each one and its arguments, please +refer to the full documentation online. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl P , Fl Fl profile +The profile to start +.Nm +with. +If this flag is not specified, +then it defaults to using +.Sy default_profile +(see +.Xr iamb 5 ) . +.It Fl C , Fl Fl config-directory +Path to the directory the configuration file is located in. +.It Fl h , Fl Fl help +Show the help text and quit. +.It Fl V , Fl Fl version +Show the current +.Nm +version and quit. +.El + +.Sh "GENERAL COMMANDS" +.Bl -tag -width Ds +.It Sy ":chats" +View a list of joined rooms and direct messages. +.It Sy ":dms" +View a list of direct messages. +.It Sy ":logout" +Log out of +.Nm . +.It Sy ":rooms" +View a list of joined rooms. +.It Sy ":spaces" +View a list of joined spaces. +.It Sy ":verify" +View a list of ongoing E2EE verifications. +.It Sy ":welcome" +View the startup Welcome window. +.El + +.Sh "MESSAGE COMMANDS" +.Bl -tag -width Ds +.It Sy ":download" +Download an attachment from the selected message. +.It Sy ":edit" +Edit the selected message. +.It Sy ":editor" +Open an external +.Ev $EDITOR +to compose a message. +.It Sy ":open" +Download and then open an attachment, or open a link in a message. +.It Sy ":react [shortcode]" +React to the selected message with an Emoji. +.It Sy ":redact [reason]" +Redact the selected message. +.It Sy ":reply" +Reply to the selected message. +.It Sy ":unreact [shortcode]" +Remove your reaction from the selected message. +When no arguments are given, remove all of your reactions from the message. +.It Sy ":upload" +Upload an attachment and send it to the currently selected room. +.El + +.Sh "ROOM COMMANDS" +.Bl -tag -width Ds +.It Sy ":create" +Create a new room. +.It Sy ":invite accept" +Accept an invitation to the currently focused room. +.It Sy ":invite reject" +Reject an invitation to the currently focused room. +.It Sy ":invite send [user]" +Send an invitation to a user to join the currently focused room. +.It Sy ":join [room]" +Join a room. +.It Sy ":leave" +Leave the currently focused room. +.It Sy ":members" +View a list of members of the currently focused room. +.It Sy ":room name set [name]" +Set the name of the currently focused room. +.It Sy ":room name unset" +Unset the name of the currently focused room. +.It Sy ":room tag set [tag]" +Add a tag to the currently focused room. +.It Sy ":room tag unset [tag]" +Remove a tag from the currently focused room. +.It Sy ":room topic set [topic]" +Set the topic of the currently focused room. +.It Sy ":room topic unset" +Unset the topic of the currently focused room. +.El + +.Sh "WINDOW COMMANDS" +.Bl -tag -width Ds +.It Sy ":horizontal [cmd]" +Change the behaviour of the given command to be horizontal. +.It Sy ":leftabove [cmd]" +Change the behaviour of the given command to open before the current window. +.It Sy ":only" , Sy ":on" +Quit all but one window in the current tab. +.It Sy ":quit" , Sy ":q" +Quit a window. +.It Sy ":quitall" , Sy ":qa" +Quit all windows in the current tab. +.It Sy ":resize" +Resize a window. +.It Sy ":rightbelow [cmd]" +Change the behaviour of the given command to open after the current window. +.It Sy ":split" , Sy ":sp" +Horizontally split a window. +.It Sy ":vertical [cmd]" +Change the layout of the following command to be vertical. +.It Sy ":vsplit" , Sy ":vsp" +Vertically split a window. +.El + +.Sh "TAB COMMANDS" +.Bl -tag -width Ds +.It Sy ":tab [cmd]" +Run a command that opens a window in a new tab. +.It Sy ":tabclose" , Sy ":tabc" +Close a tab. +.It Sy ":tabedit [room]" , Sy ":tabe" +Open a room in a new tab. +.It Sy ":tabrewind" , Sy ":tabr" +Go to the first tab. +.It Sy ":tablast" , Sy ":tabl" +Go to the last tab. +.It Sy ":tabnext" , Sy ":tabn" +Go to the next tab. +.It Sy ":tabonly" , Sy ":tabo" +Close all but one tab. +.It Sy ":tabprevious" , Sy ":tabp" +Go to the preview tab. +.El + +.Sh EXAMPLES +.Ss Example 1: Starting with a specific profile +To start with a profile named +.Sy personal +instead of the +.Sy default_profile +value: +.Bd -literal -offset indent +$ iamb -P personal +.Ed +.Ss Example 2: Using an alternate configuration directory +By default, +.Nm +will use the XDG directories, but you may sometimes want to store +your configuration elsewhere. +.Bd -literal -offset indent +$ iamb -C ~/src/iamb-dev/dev-config/ +.Ed +.Sh "REPORTING BUGS" +Please report bugs in +.Nm +or its manual pages at +.Lk https://github.com/ulyssa/iamb/issues +.Sh "SEE ALSO" +.Xr iamb 5 +.Pp +Extended documentation is available online at +.Lk https://iamb.chat diff --git a/docs/iamb.1.md b/docs/iamb.1.md deleted file mode 100644 index ca33ea1..0000000 --- a/docs/iamb.1.md +++ /dev/null @@ -1,29 +0,0 @@ -# NAME - -iamb – a terminal-based client for Matrix for the Vim addict - -# SYNOPSIS - -**iamb** [**--profile** _profile_] [**--config-directory** _directory_] [**--help** | **--version**] - -# OPTIONS - -These options are primitives at the top-level of the file. - -**--profile**, **-P** -> The profile to start with. Overrides **default_profile** from **iamb(5)**. - -**--config-directory**, **-C** -> Path to the directory the configuration file is located in. - -**--help**, **-h** -> Show a short help text and quit. - -**--version**, **-V** -> Show the iamb version and quit. - -# SEE ALSO - -**iamb(5)** - -Full documentation is available online at \ diff --git a/docs/iamb.5 b/docs/iamb.5 new file mode 100644 index 0000000..48c5412 --- /dev/null +++ b/docs/iamb.5 @@ -0,0 +1,555 @@ +.\" iamb(7) manual page +.\" +.\" This manual page is written using the mdoc(7) macros. For more +.\" information, see . +.\" +.\" You can preview this file with: +.\" $ man ./docs/iamb.1 +.Dd Mar 24, 2024 +.Dt IAMB 5 +.Os +.Sh NAME +.Nm config.toml +.Nd configuration file for +.Sy iamb +.Sh DESCRIPTION +Configuration must be placed under +.Pa ~/.config/iamb/ +and named +.Nm . +(If +.Ev $XDG_CONFIG_HOME +is set, then +.Sy iamb +will look for a directory named +.Pa iamb +there instead.) +.Pp +Example configuration usually comes bundled with your installation and can +typically be found in +.Pa /usr/share/iamb . +.Pp +As implied by the filename, the configuration is formatted in TOML. +It's structure and fields are described below. +.Sh CONFIGURATION +These options are sections at the top-level of the file. +.Bl -tag -width Ds +.It Sy profiles +A map of profile names containing per-account information. +See +.Sx PROFILES . +.It Sy default_profile +The name of the default profile to connect to, unless overwritten by a +commandline switch. +It should be one of the names defined in the +.Sy profiles +section. +.It Sy settings +Overwrite general settings for +.Sy iamb . +See +.Sx SETTINGS +for a description of possible values. +.It Sy layout +Configure the default window layout to use when starting +.Sy iamb . +See +.Sx "STARTUP LAYOUT" +for more information on how to configure this object. +.It Sy macros +Map keybindings to other keybindings. +See +.Sx "CUSTOM KEYBINDINGS" +for how to configure this object. +.It Sy dirs +Configure the directories to use for data, logs, and more. +See +.Sx DIRECTORIES +for the possible values you can set in this object. +.El +.Sh PROFILES +These options are configured as fields in the +.Sy profiles +object. +.Bl -tag -width Ds +.It Sy user_id +The user ID to use when connecting to the server. +For example "user" in "@user:matrix.org". +.It Sy url +The URL of the user's server. +(For example "https://matrix.org" for "@user:matrix.org".) +This is only needed when the server does not have a +.Pa /.well-known/matrix/client +entry. +.El +.Pp +In addition to the above fields, you can also reuse the following fields to set +per-profile overrides of their global values: +.Bl -bullet -offset indent -width 1m +.It +.Sy dirs +.It +.Sy layout +.It +.Sy macros +.It +.Sy settings +.El +.Ss Example 1: A single profile +.Bd -literal -offset indent +[profiles.personal] +user_id = "@user:matrix.org" +.Ed +.Ss Example 2: Two profiles with a default +In the following example, there are two profiles, +.Dq personal +(set to be the default) and +.Dq work . +The +.Dq work +profile has an explicit URL set for its homeserver. +.Bd -literal -offset indent +default_profile = "personal" + +[profiles.personal] +user_id = "@user:matrix.org" + +[profiles.work] +user_id = "@user:example.com" +url = "https://matrix.example.com" +.Ed +.Sh SETTINGS +These options are configured as an object under the +.Sy settings +key and can be overridden as described in +.Sx PROFILES . +.Bl -tag -width Ds + +.It Sy default_room +The room to show by default instead of the +.Sy :welcome +window. + +.It Sy image_preview +Enable image previews and configure it. +An empty object will enable the feature with default settings, omitting it will disable the feature. +The available fields in this object are: +.Bl -tag -width Ds +.It Sy size +An optional object with +.Sy width +and +.Sy height +fields to specify the preview size in cells. +Defaults to 66 and 10. +.It Sy protocol +An optional object to override settings that will normally be guessed automatically: +.Bl -tag -width Ds +.It Sy type +An optional string set to one of the protocol types: +.Dq Sy sixel , +.Dq Sy kitty , and +.Dq Sy halfblocks . +.It Sy font_size +An optional list of two numbers representing font width and height in pixels. +.El +.El +.It Sy log_level +Specifies the lowest log level that should be shown. +Possible values are: +.Dq Sy trace , +.Dq Sy debug , +.Dq Sy info , +.Dq Sy warn , and +.Dq Sy error . + +.It Sy message_shortcode_display +Defines whether or not Emoji characters in messages should be replaced by their +respective shortcodes. + +.It Sy message_user_color +Defines whether or not the message body is colored like the username. + +.It Sy notifications +When this subsection is present, you can enable and configure push notifications. +See +.Sx NOTIFICATIONS +for more details. + +.It Sy open_command +Defines a custom command and its arguments to run when opening downloads instead of the default. +(For example, +.Sy ["my-open",\ "--file"] . ) + +.It Sy reaction_display +Defines whether or not reactions should be shown. + +.It Sy reaction_shortcode_display +Defines whether or not reactions should be shown as their respective shortcode. + +.It Sy read_receipt_send +Defines whether or not read confirmations are sent. + +.It Sy read_receipt_display +Defines whether or not read confirmations are displayed. + +.It Sy request_timeout +Defines the maximum time per request in seconds. + +.It Sy sort +Configures how to sort the lists shown in windows like +.Sy :rooms +or +.Sy :members . +See +.Sx "SORTING LISTS" +for more details. + +.It Sy typing_notice_send +Defines whether or not the typing state is sent. + +.It Sy typing_notice_display +Defines whether or not the typing state is displayed. + +.It Sy user +Overrides values for the specified user. +See +.Sx "USER OVERRIDES" +for details on the format. + +.It Sy username_display +Defines how usernames are shown for message senders. +Possible values are +.Dq Sy username , +.Dq Sy localpart , or +.Dq Sy displayname . + +.It Sy user_gutter_width +Specify the width of the column where usernames are displayed in a room. +Usernames that are too long are truncated. +Defaults to 30. +.El + +.Ss Example 1: Avoid showing Emojis (useful for terminals w/o support) +.Bd -literal -offset indent +[settings] +username = "username" +message_shortcode_display = true +reaction_shortcode_display = true +.Ed + +.Ss Example 2: Increase request timeout to 2 minutes for a slow homeserver +.Bd -literal -offset indent +[settings] +request_timeout = 120 +.Ed + +.Sh NOTIFICATIONS + +The +.Sy settings.notifications +subsection allows configuring how notifications for new messages behave. + +The available fields in this subsection are: +.Bl -tag -width Ds +.It Sy enabled +Defaults to +.Sy false . +Setting this field to +.Sy true +enables notifications. + +.It Sy via +Defaults to +.Dq Sy desktop +to use the desktop mechanism (default). +Setting this field to +.Dq Sy bell +will use the terminal bell instead. + +.It Sy show_message +controls whether to show the message in the desktop notification, and defaults to +.Sy true . +Messages are truncated beyond a small length. +The notification rules are stored server side, loaded once at startup, and are currently not configurable in iamb. +In other words, you can simply change the rules with another client. +.El + +.Ss Example 1: Enable notifications with default options +.Bd -literal -offset indent +[settings] +notifications = {} +.Ed +.Ss Example 2: Enable notifications using terminal bell +.Bd -literal -offset indent +[settings.notifications] +via = "bell" +show_message = false +.Ed + +.Sh "SORTING LISTS" + +The +.Sy settings.sort +subsection allows configuring how different windows have their contents sorted. + +Fields available within this subsection are: +.Bl -tag -width Ds +.It Sy rooms +How to sort the +.Sy :rooms +window. +Defaults to +.Sy ["favorite",\ "lowpriority",\ "unread",\ "name"] . +.It Sy chats +How to sort the +.Sy :chats +window. +Defaults to the +.Sy rooms +value. +.It Sy dms +How to sort the +.Sy :dms +window. +Defaults to the +.Sy rooms +value. +.It Sy spaces +How to sort the +.Sy :spaces +window. +Defaults to the +.Sy rooms +value. +.It Sy members +How to sort the +.Sy :members +window. +Defaults to +.Sy ["power",\ "id"] . +.El +.El + +.Ss Example 1: Group room members by ther server first +.Bd -literal -offset indent +[settings.sort] +members = ["server", "localpart"] +.Ed + +.Sh "USER OVERRIDES" + +The +.Sy settings.users +subsections allows overriding how specific senders are displayed. +Overrides are mapped onto Matrix User IDs such as +.Sy @user:matrix.org , +and are typically written as inline tables containing the following keys: + +.Bl -tag -width Ds +.It Sy name +Change the display name of the user. + +.It Sy color +Change the color the user is shown as. +Possible values are: +.Dq Sy black , +.Dq Sy blue , +.Dq Sy cyan , +.Dq Sy dark-gray , +.Dq Sy gray , +.Dq Sy green , +.Dq Sy light-blue , +.Dq Sy light-cyan , +.Dq Sy light-green , +.Dq Sy light-magenta , +.Dq Sy light-red , +.Dq Sy light-yellow , +.Dq Sy magenta , +.Dq Sy none , +.Dq Sy red , +.Dq Sy white , +and +.Dq Sy yellow . +.El + +.Ss Example 1: Override how @ada:example.com appears in chat +.Bd -literal -offset indent +[settings.users] +"@ada:example.com" = { name = "Ada Lovelace", color = "light-red" } +.Ed + +.Sh STARTUP LAYOUT + +The +.Sy layout +section allows configuring the initial set of tabs and windows to show when +starting the client. + +.Bl -tag -width Ds +.It Sy style +Specifies what window layout to load when starting. +Valid values are +.Dq Sy restore +to restore the layout from the last time the client was exited, +.Dq Sy new +to open a single window (uses the value of +.Sy default_room +if set), or +.Dq Sy config +to open the layout described under +.Sy tabs . + +.It Sy tabs +If +.Sy style +is set to +.Sy config , +then this value will be used to open a set of tabs and windows at startup. +Each object can contain either a +.Sy window +key specifying a username, room identifier or room alias to show, or a +.Sy split +key specifying an array of window objects. +.El + +.Ss Example 1: Show a single room every startup +.Bd -literal -offset indent +[settings] +default_room = "#iamb-users:0x.badd.cafe" + +[layout] +style = "new" +.Ed +.Ss Example 2: Show a specific layout every startup +.Bd -literal -offset indent +[layout] +style = "config" + +[[layout.tabs]] +window = "iamb://dms" + +[[layout.tabs]] +window = "iamb://rooms" + +[[layout.tabs]] +split = [ + { "window" = "#iamb-users:0x.badd.cafe" }, + { "window" = "#iamb-dev:0x.badd.cafe" } +] +.Ed + +.Sh "CUSTOM KEYBINDINGS" + +The +.Sy macros +subsections allow configuring custom keybindings. +Available subsections are: + +.Bl -tag -width Ds +.It Sy insert , Sy i +Map the key sequences in this section in +.Sy Insert +mode. + +.It Sy normal , Sy n +Map the key sequences in this section in +.Sy Normal +mode. + +.It Sy visual , Sy v +Map the key sequences in this section in +.Sy Visual +mode. + +.It Sy select +Map the key sequences in this section in +.Sy Select +mode. + +.It Sy command , Sy c +Map the key sequences in this section in +.Sy Visual +mode. + +.It Sy operator-pending +Map the key sequences in this section in +.Sy "Operator Pending" +mode. +.El + +Multiple modes can be given together by separating their names with +.Dq Sy | . + +.Ss Example 1: Use "jj" to exit Insert mode +.Bd -literal -offset indent +[macros.insert] +"jj" = "" +.Ed + +.Ss Example 2: Use "V" for switching between message bar and room history +.Bd -literal -offset indent +[macros."normal|visual"] +"V" = "m" +.Ed + +.Sh DIRECTORIES + +Specifies the directories to save data in. +Configured as an object under the key +.Sy dirs . + +.Bl -tag -width Ds +.It Sy cache +Specifies where to store assets and temporary data in. +(For example, +.Sy image_preview +and +.Sy logs +will also go in here by default.) +Defaults to +.Ev $XDG_CACHE_HOME/iamb . + +.It Sy data +Specifies where to store persistent data in, such as E2EE room keys. +Defaults to +.Ev $XDG_DATA_HOME/iamb . + +.It Sy downloads +Specifies where to store downloaded files. +Defaults to +.Ev $XDG_DOWNLOAD_DIR . + +.It Sy image_previews +Specifies where to store automatically downloaded image previews. +Defaults to +.Ev ${cache}/image_preview_downloads . + +.It Sy logs +Specifies where to store log files. +Defaults to +.Ev ${cache}/logs . +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa ~/.config/iamb/config.toml +The TOML configuration file that +.Sy iamb +loads by default. +.It Pa ~/.config/iamb/config.json +A JSON configuration file that +.Sy iamb +will load if the TOML one is not found. +.It Pa /usr/share/iamb/config.example.toml +A sample configuration file with examples of how to set different values. +.El +.Sh "REPORTING BUGS" +Please report bugs in +.Sy iamb +or its manual pages at +.Lk https://github.com/ulyssa/iamb/issues +.Sh SEE ALSO +.Xr iamb 1 +.Pp +Extended documentation is available online at +.Lk https://iamb.chat diff --git a/docs/iamb.5.md b/docs/iamb.5.md deleted file mode 100644 index 3d95776..0000000 --- a/docs/iamb.5.md +++ /dev/null @@ -1,171 +0,0 @@ -# NAME - -config.json – configuration file for iamb - -# SYNOPSIS - -Configuration must be placed under _~/.config/iamb/_ and is named config.json. - -Example configuration usually comes bundled with your installation and can -typically be found in _/usr/share/iamb_. - -As implied by the filename, the configuration is formatted in JSON. It's -structure and fields are described below. - -# BASIC SETTINGS - -These options are primitives at the top-level of the file. - -**default_profile** (type: string) -> The default profile to connect to, unless overwritten by a commandline -> switch. It has to be defined in the *PROFILES* section. - -# PROFILES - -These options are configured as a map under the profiles name. - -**user_id** (type: string) -> The user ID to use when connecting to the server. For example "user" for -> "@user:matrix.org". - -**url** (type: string) -> The URL of the users server. For example "https://matrix.org" for -> "@user:matrix.org". - -**settings** (type: settings object) -> Overwrite general settings for this account. The fields are identical to -> those in *TUNABLES*. - -**layout** (type: startup layout object) -> Overwrite general settings for this account. The fields are identical to -> those in *STARTUP LAYOUT*. - -**dirs** (type: XDG overrides object) -> Overwrite general settings for this account. The fields are identical to -> those in *DIRECTORIES*. - -# TUNABLES - -These options are configured as a map under the *settings* key and can be -overridden as described in *PROFILES*. - -**log_level** (type: string) -> Specifies the lowest log level that should be shown. Possible values -> are: _trace_, _debug_, _info_, _warn_, and _error_. - -**message_shortcode_display** (type: boolean) -> Defines whether or not emoji characters in messages should be replaced by -> their respective shortcodes. - -**reaction_display** (type: boolean) -> Defines whether or not reactions should be shown. - -**reaction_shortcode_display** (type: boolean) -> Defines whether or not reactions should be shown as their respective -> shortcode. - -**read_receipt_send** (type: boolean) -> Defines whether or not read confirmations are sent. - -**read_receipt_display** (type: boolean) -> Defines whether or not read confirmations are displayed. - -**request_timeout** (type: uint64) -> Defines the maximum time per request in seconds. - -**typing_notice_send** (type: boolean) -> Defines whether or not the typing state is sent. - -**typing_notice_display** (type: boolean) -> Defines whether or not the typing state is displayed. - -**user** (type: map) -> Overrides values for the specified user. See *USER OVERRIDES* for -> details on the format. - -**default_room** (type: string) -> The room to show by default instead of a welcome-screen. - -**message_user_color** (type: boolean) -> Defines whether or not the message body is colored like the username. - -**notifications** (type: notifications object) -> Configures push-notifications. -> *enabled* `true` to enable the feature, defaults to `false`. -> *via* `"desktop"` to use desktop mechanism (default), or `"bell"` to use -> terminal bell. -> *show_message* to show the message in the desktop notification. Defaults -> to `true`. Messages are truncated beyond a small length. -> The notification _rules_ are stored server side, loaded once at startup, -> and are currently not configurable in iamb. In other words, you can -> simply change the rules with another client. - -**image_preview** (type: image_preview object) -> Enable image previews and configure it. An empty object will enable the -> feature with default settings, omitting it will disable the feature. -> *size* is an optional object with *width* and *height* numbers, which are -> used to set the preview size in characters. Defaults to 66 and 10. -> *protocol* is an optional object to override settings that should normally -> be guessed automatically. -> *protocol.type* is an optional string with one of the protocol types: -> _sixel_, _kitty_, _halfblocks_. -> *protocol.font_size* is an optional list of two numbers representing font -> width and height in pixels. - -**user_gutter_width** (type: usize) -> Specify the width of the column where usernames are displayed in a room. -> Usernames that are too long are truncated. - -## USER OVERRIDES - -Overrides are mapped onto matrix User IDs such as _@user:matrix.org_ and are -maps containing the following key value pairs. - -**name** (type: string) -> Change the display name of the user. - -**color** (type: string) -> Change the color the user is shown as. Possible values are: _black_, -> _blue_, _cyan_, _dark-gray_, _gray_, _green_, _light-blue_, -> _light-cyan_, _light-green_, _light-magenta_, _light-red_, -> _light-yellow_, _magenta_, _none_, _red_, _white_, _yellow_ - -# STARTUP LAYOUT - -Specifies what initial set of tabs and windows to show when starting the -client. Configured as an object under the key *layout*. - -**style** (type: string) -> Specifies what window layout to load when starting. Valid values are -> _restore_ to restore the layout from the last time the client was exited, -> _new_ to open a single window (uses the value of _default\_room_ if set), or -> _config_ to open the layout described under _tabs_. - -**tabs** (type: array of window objects) -> If **style** is set to _config_, then this value will be used to open a set -> of tabs and windows at startup. Each object can contain either a **window** -> key specifying a username, room identifier or room alias to show, or a -> **split** key specifying an array of window objects. - -# DIRECTORIES - -Specifies the directories to save data in. Configured as a map under the key -*dirs*. - -**cache** (type: string) -> Specifies where to store assets and temporary data in. - -**logs** (type: string) -> Specifies where to store log files. - -**downloads** (type: string) -> Specifies where to store downloaded files. - -**image_previews** (type: string) -> Specifies where to store automatically downloaded image previews. - -# SEE ALSO - -*iamb(1)* - -Full documentation is available online at \