Add manual pages (#88)

.gitignore

@@ -1,2 +1,3 @@
 /target
 /TODO
+/docs/iamb.[15]

Cargo.lock

@@ -867,6 +867,12 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "850878694b7933ca4c9569d30a34b55031b9b139ee1fc7b94a527c4ef960d690"
 
+[[package]]
+name = "deunicode"
+version = "1.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8c1bba4f227a4a53d12b653f50ca7bf10c9119ae2aba56aff9e0338b5c98f36a"
+
 [[package]]
 name = "digest"
 version = "0.9.0"
@@ -1298,6 +1304,15 @@ dependencies = [
  "windows 0.43.0",
 ]
 
+[[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.1.16"
@@ -1511,6 +1526,7 @@ dependencies = [
  "html5ever",
  "image",
  "lazy_static 1.4.0",
+ "mandown",
  "markup5ever_rcdom",
  "matrix-sdk",
  "mime",
@@ -1830,6 +1846,16 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "mandown"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "12243a468e9660b178540f73c43bdc544d64bd3cde749de0bd851e0dbacfd683"
+dependencies = [
+ "deunicode 1.3.3",
+ "pulldown-cmark",
+]
+
 [[package]]
 name = "maplit"
 version = "1.0.2"
@@ -2599,6 +2625,18 @@ dependencies = [
  "syn 1.0.109",
 ]
 
+[[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 = "quick-xml"
 version = "0.28.1"
@@ -3367,7 +3405,7 @@ version = "0.1.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b3bc762e6a4b6c6fcaade73e77f9ebc6991b676f88bb2358bddb56560f073373"
 dependencies = [
- "deunicode",
+ "deunicode 0.4.3",
 ]
 
 [[package]]

Cargo.toml

@@ -14,6 +14,9 @@ categories = ["command-line-utilities"]
 rust-version = "1.66"
 build = "build.rs"
 
+[build-dependencies]
+mandown = "0.1.3"
+
 [build-dependencies.vergen]
 version = "8"
 default-features = false

build.rs

@@ -1,7 +1,26 @@
 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);
+
+    fs::write(PathBuf::from_iter(["docs", "iamb.1"]), iamb_1.as_bytes())?;
+    fs::write(PathBuf::from_iter(["docs", "iamb.5"]), iamb_5.as_bytes())?;
+
     Ok(())
 }

docs/example_config.json

@@ -0,0 +1,32 @@
+{
+	"default_profile": "default",
+	"profiles": {
+		"default": {
+			"user_id":  "",
+			"url":      "https://matrix.org",
+			"settings": {},
+			"dirs":     {}
+		}
+	},
+	"settings": {
+		"log_level":                  "warn",
+		"reaction_display":           true,
+		"reaction_shortcode_display": false,
+		"read_receipt_send":          true,
+		"read_receipt_display":       true,
+		"request_timeout":            10000,
+		"typing_notice_send":         true,
+		"typing_notice_display":      true,
+		"users": {
+			"@user:matrix.org": {
+				"name":  "John Doe",
+				"color": "magenta"
+			}
+		},
+		"default_room": "#iamb-users:0x.badd.cafe"
+	},
+	"dirs": {
+		"cache":     "~/.cache/iamb/",
+		"logs":      "~/.local/share/iamb/logs/",
+		"downloads": "~/Downloads/"
+	}

docs/iamb.1.md

@@ -0,0 +1,29 @@
+# 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\>

docs/iamb.5.md

@@ -0,0 +1,113 @@
+# 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*.
+
+**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_.
+
+**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.
+
+## 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_
+
+# 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.
+
+# SEE ALSO
+
+*iamb(1)*
+
+Full documentation is available online at \<https://iamb.chat\>