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

.gitignore

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

Cargo.toml

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

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

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<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(())
 }

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

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