youwen/iamb
1
0
Fork 0
mirror of https://github.com/youwen5/iamb.git synced 2025-06-19 05:09:51 -07:00
Code Issues Projects Releases Packages Wiki Activity

Update manual pages to use mdoc(7) and list commands (#230)

Browse source
This commit is contained in:
Ulyssa 2024-03-26 08:55:22 -07:00 • committed by GitHub
parent ed1b88c197
commit 6600685dd5
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 778 additions and 266 deletions
Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -1,5 +1,4 @@
/target
/result
/TODO
/docs/iamb.[15]
.direnv

42
Cargo.lock generated
View file

@ -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]]

5
Cargo.toml
View file

@ -1,6 +1,6 @@
[package]
name = "iamb"
version = "0.0.9-alpha.1"
version = "0.0.9"
edition = "2018"
authors = ["Ulyssa <git@ulyssa.dev>"]
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

11
PACKAGING.md
View file

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

20
build.rs
View file

@ -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<dyn Error>> {
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(())
}

14
config.example.toml
View file

@ -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" = "<Esc>"

196
docs/iamb.1 Normal file
View file

@ -0,0 +1,196 @@
.\" iamb(1) manual page
.\"
.\" This manual page is written using the mdoc(7) macros. For more
.\" information, see <https://manpages.bsd.lv/mdoc.html>.
.\"
.\" 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

29
docs/iamb.1.md
View file

@ -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 \<https://iamb.chat\>

555
docs/iamb.5 Normal file
View file

@ -0,0 +1,555 @@
.\" iamb(7) manual page
.\"
.\" This manual page is written using the mdoc(7) macros. For more
.\" information, see <https://manpages.bsd.lv/mdoc.html>.
.\"
.\" 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" = "<Esc>"
.Ed
.Ss Example 2: Use "V" for switching between message bar and room history
.Bd -literal -offset indent
[macros."normal|visual"]
"V" = "<C-W>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

171
docs/iamb.5.md
View file

@ -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 \<https://iamb.chat\>