From 4684f9fa4774dd733b91e82350d7c230434ed51d Mon Sep 17 00:00:00 2001
From: Isaac Freund <ifreund@ifreund.xyz>
Date: Sat, 1 May 2021 12:49:49 +0200
Subject: [PATCH] rivertile: add -h/--help, improve man page

---
 doc/rivertile.1.scd | 30 ++++++++++++++++++++++++------
 rivertile/main.zig  | 22 ++++++++++++++++++++++
 2 files changed, 46 insertions(+), 6 deletions(-)

diff --git a/doc/rivertile.1.scd b/doc/rivertile.1.scd
index 751e327..b196062 100644
--- a/doc/rivertile.1.scd
+++ b/doc/rivertile.1.scd
@@ -10,28 +10,36 @@ rivertile - Tiled layout generator for river
 
 # DESCRIPTION
 
-*rivertile* is a layout client for river. It provides a simple tiled layout
-split main/secondary stacks.
+*rivertile* is a layout client for *river*(1). It provides a simple tiled
+layout with split main/secondary stacks. The initial state may be configured
+with various options passed on startup. Some values may additionally be
+modified while rivertile is running with the help of *riverctl*(1).
 
 # OPTIONS
 
 *-view-padding* _pixels_
-	Set the padding around views in pixels.
+	Set the padding around views in pixels. (Default: 6)
 
 *-outer-padding* _pixels_
 	Set the padding around the edge of the layout area in pixels.
+	(Default: 6)
 
 *-main-location* [*top*|*bottom*|*left*|*right*]
-	Set the default location of the main area in the layout.
+	Set the initial location of the main area in the layout.
+	(Default: *left*)
 
 *-main-count* _count_
-	Set the default number of views in the main area of the layout.
+	Set the initial number of views in the main area of the
+	layout. (Default: 1)
 
 *-main-factor* _ratio_
-	Set the default ratio of main area to total layout area.
+	Set the initial ratio of main area to total layout area. (Default: 0.6)
 
 # VALUES
 
+These values may be modified while rivertile is running with the help of
+*riverctl*(1).
+
 _main_location_ (string: top, bottom, left, or right)
 	The location of the main area in the layout.
 
@@ -41,6 +49,16 @@ _main_count_ (int)
 _main_factor_ (fixed: [0.1, 0.9])
 	The ratio of main area to total layout area.
 
+# EXAMPLES
+
+Start *rivertile* with 4 pixels outer padding and 2 main views:
+
+	rivertile -outer-padding 4 -main-count 2
+
+Set the main location of rivertile to top at runtime:
+
+	riverctl send-layout-value rivertile string main_location top
+
 # AUTHORS
 
 Maintained by Isaac Freund <ifreund@ifreund.xyz> who is assisted by open
diff --git a/rivertile/main.zig b/rivertile/main.zig
index 27e03ca..780b78c 100644
--- a/rivertile/main.zig
+++ b/rivertile/main.zig
@@ -48,6 +48,22 @@ const river = wayland.client.river;
 const Args = @import("args.zig").Args;
 const FlagDef = @import("args.zig").FlagDef;
 
+const usage =
+    \\Usage: rivertile [options]
+    \\
+    \\  -h, --help      Print this help message and exit.
+    \\  -view-padding   Set the padding around views in pixels. (Default 6)
+    \\  -outer-padding  Set the padding around the edge of the layout area in
+    \\                  pixels. (Default 6)
+    \\  -main-location  Set the initial location of the main area in the
+    \\                  layout. (Default left)
+    \\  -main-count     Set the initial number of views in the main area of the
+    \\                  layout. (Default 1)
+    \\  -main-factor    Set the initial ratio of main area to total layout
+    \\                  area. (Default: 0.6)
+    \\
+;
+
 const Location = enum {
     top,
     right,
@@ -262,6 +278,8 @@ pub fn main() !void {
     // https://github.com/ziglang/zig/issues/7807
     const argv: [][*:0]const u8 = std.os.argv;
     const args = Args(0, &[_]FlagDef{
+        .{ .name = "-h", .kind = .boolean },
+        .{ .name = "--help", .kind = .boolean },
         .{ .name = "-view-padding", .kind = .arg },
         .{ .name = "-outer-padding", .kind = .arg },
         .{ .name = "-main-location", .kind = .arg },
@@ -269,6 +287,10 @@ pub fn main() !void {
         .{ .name = "-main-factor", .kind = .arg },
     }).parse(argv[1..]);
 
+    if (args.boolFlag("-h") or args.boolFlag("--help")) {
+        std.io.getStdOut().writeAll(usage);
+        std.os.exit(0);
+    }
     if (args.argFlag("-view-padding")) |raw| {
         view_padding = std.fmt.parseUnsigned(u32, mem.span(raw), 10) catch
             fatal("invalid value '{s}' provided to -view-padding", .{raw});