docs: add a man page

.gitignore

@@ -1,2 +1,3 @@
 zig-cache
 zig-out
+/doc/waylock.1

README.md

@@ -29,6 +29,7 @@ installed:
 - xkbcommon
 - pam
 - pkg-config
+- scdoc (optional, but required for man page generation)
 
 Then run, for example:
 
@@ -43,7 +44,8 @@ installing to a prefix other than `/usr` to ensure the configuration file
 
 ## Usage
 
-See `waylock -h` for an overview of the command line options.
+See the `waylock(1)` man page or the output of `waylock -h` for an overview
+of the command line options.
 
 Run the waylock executable to lock the session. All monitors will be
 blanked with the `-init-color`. Typing causes the color to change to the

build.zig

@@ -1,5 +1,5 @@
 const std = @import("std");
-const Builder = std.build.Builder;
+const zbs = std.build;
 const fs = std.fs;
 const mem = std.mem;
 
@@ -11,10 +11,27 @@ const ScanProtocolsStep = @import("deps/zig-wayland/build.zig").ScanProtocolsSte
 /// Directly after the tagged commit, the version should be bumped and the "-dev" suffix added.
 const version = "0.4.0-dev";
 
-pub fn build(b: *Builder) !void {
+pub fn build(b: *zbs.Builder) !void {
     const target = b.standardTargetOptions(.{});
     const mode = b.standardReleaseOptions();
 
+    const man_pages = b.option(
+        bool,
+        "man-pages",
+        "Set to true to build man pages. Requires scdoc. Defaults to true if scdoc is found.",
+    ) orelse scdoc_found: {
+        _ = b.findProgram(&[_][]const u8{"scdoc"}, &[_][]const u8{}) catch |err| switch (err) {
+            error.FileNotFound => break :scdoc_found false,
+            else => return err,
+        };
+        break :scdoc_found true;
+    };
+
+    if (man_pages) {
+        const scdoc_step = try ScdocStep.create(b);
+        try scdoc_step.install();
+    }
+
     const install_prefix = try std.fs.path.resolve(b.allocator, &[_][]const u8{b.install_prefix});
     if (std.mem.eql(u8, install_prefix, "/usr")) {
         b.installFile("pam.d/waylock", "../etc/pam.d/waylock");
@@ -67,3 +84,29 @@ pub fn build(b: *Builder) !void {
 
     waylock.install();
 }
+
+const ScdocStep = struct {
+    builder: *zbs.Builder,
+    step: zbs.Step,
+
+    fn create(builder: *zbs.Builder) !*ScdocStep {
+        const self = try builder.allocator.create(ScdocStep);
+        self.* = .{
+            .builder = builder,
+            .step = zbs.Step.init(.custom, "Generate man pages", builder.allocator, make),
+        };
+        return self;
+    }
+
+    fn make(step: *zbs.Step) !void {
+        const self = @fieldParentPtr(ScdocStep, "step", step);
+        _ = try self.builder.exec(
+            &[_][]const u8{ "sh", "-c", "scdoc < doc/waylock.1.scd > doc/waylock.1" },
+        );
+    }
+
+    fn install(self: *ScdocStep) !void {
+        self.builder.getInstallStep().dependOn(&self.step);
+        self.builder.installFile("doc/waylock.1", "share/man/man1/waylock.1");
+    }
+};

doc/waylock.1.scd

@@ -0,0 +1,59 @@
+WAYLOCK(1) "github.com/ifreund/waylock" "General Commands Manual"
+
+# NAME
+
+waylock - a small Wayland screenocker
+
+# SYNOPSIS
+
+*waylock* [_options_]
+
+# DESCRIPTION
+
+Waylock is a small screenlocker for Wayland compositors implementing
+*ext-session-lock-v1*. The *ext-session-lock-v1* protocol is significantly
+more robust than previous client-side Wayland screen locking approaches.
+Importantly, the screenlocker crashing does not cause the session to be
+unlocked.
+
+# OPTIONS
+
+*-h*
+	Print a help message and exit.
+
+*-version*
+	Print the version number and exit.
+
+*-log-level* [*error*|*warning*|*info*|*debug*]
+	Set the log level of waylock. At the *error* log level, only errors
+	are logged.  At the *debug* log level, everything is logged including
+	verbose debug messages.
+
+*-init-color* _0xRRGGBB_
+	Set the initial color. (default: 0x002b36)
+
+*-input-color* _0xRRGGBB_
+	Set the color used after input. (default: 0x6c71c4)
+
+*-fail-color* _0xRRGGBB_
+	Set the color used on authentication failure. (default: 0xdc322f)
+
+# USAGE
+
+Run the waylock executable to lock the session. All monitors will be
+blanked with the *-init-color*. Typing causes the color to change to the
+*-input-color*, to clear what you've typed press Esc or Ctrl-U.
+
+To unlock the session, type your password and press Enter. If the password
+is correct, waylock will unlock the session and exit. Otherwise, the color
+will change to the *-fail-color* and you may try again.
+
+# AUTHORS
+
+Maintained by Isaac Freund <mail@isaacfreund.com> who is assisted by open
+source contributors. For more information about waylock's development, see
+https://github.com/ifreund/waylock.
+
+# SEE ALSO
+
+*pam*(8)

src/main.zig

@@ -13,13 +13,13 @@ const flags = @import("flags.zig");
 const usage =
     \\usage: waylock [options]
     \\
-    \\  -h                   Print this help message and exit.
-    \\  -version             Print the version number and exit.
-    \\  -log-level <level>   Set the log level to error, warning, info, or debug.
+    \\  -h                     Print this help message and exit.
+    \\  -version               Print the version number and exit.
+    \\  -log-level <level>     Set the log level to error, warning, info, or debug.
     \\
-    \\  -init-color <color>  Set the initial color. (default: 0x002b36)
-    \\  -input-color <color> Set the color used after input. (default: 0x6c71c4)
-    \\  -fail-color <color>  Set the color used on authentication failure. (default: 0xdc322f)
+    \\  -init-color 0xRRGGBB   Set the initial color.
+    \\  -input-color 0xRRGGBB  Set the color used after input.
+    \\  -fail-color 0xRRGGBB   Set the color used on authentication failure.
     \\
 ;