doc: generate manpages with scdoc

Signed-off-by: NotAShelf <raf@notashelf.dev>
Change-Id: I76a1ac451259af5b4eb86a609b367ca36a6a6964

doc/beer.1.scd

@@ -0,0 +1,92 @@
+beer(1)
+
+# NAME
+
+beer - a fast, software-rendered, Wayland-native terminal emulator
+
+# SYNOPSIS
+
+*beer* [_options_]
+
+# DESCRIPTION
+
+*beer* is a lightweight, CPU-rendered terminal emulator for Wayland. It spawns
+the user's login shell in a pseudo-terminal and renders its output into a
+server-decorated window, with truecolor, styled text, scrollback, incremental
+search, mouse selection, and clipboard integration.
+
+# OPTIONS
+
+*--server*
+	Run as a daemon hosting multiple windows. (Not yet implemented.)
+
+*--config* _PATH_
+	Load configuration from _PATH_ instead of the default location (see
+	*FILES*).
+
+*-h*, *--help*
+	Print usage and exit.
+
+*-V*, *--version*
+	Print the version and exit.
+
+# KEY BINDINGS
+
+These are the built-in defaults; all are configurable in the *key-bindings*
+table of _beer.toml_(5).
+
+[[ *Binding*
+:< *Action*
+|  Ctrl+Shift+C
+:  Copy the selection to the clipboard
+|  Ctrl+Shift+V
+:  Paste from the clipboard
+|  Ctrl+Shift+F
+:  Start incremental scrollback search
+|  Shift+Page_Up / Shift+Page_Down
+:  Scroll the viewport one page
+|  Ctrl+Shift+Home / Ctrl+Shift+End
+:  Scroll to the top / bottom of history
+|  Ctrl+Plus / Ctrl+Equal / Ctrl+Minus
+:  Increase / decrease the font size
+|  Ctrl+0
+:  Reset the font size
+|  F11
+:  Toggle fullscreen
+
+In incremental search, type to refine the query, *Up*/*Return* jumps to the
+previous match, *Down* to the next, and *Escape* exits.
+
+# MOUSE
+
+Left-click and drag selects text; double-click selects a word, triple-click a
+line, and Ctrl+drag selects a rectangular block. The selection is copied to the
+primary selection on release; middle-click pastes it. The wheel scrolls
+history. Holding *Shift* forces local selection even while an application has
+requested mouse reporting.
+
+# ENVIRONMENT
+
+*SHELL*
+	The shell to spawn; defaults to _/bin/sh_.
+
+*TERM*
+	Set to the configured terminal name (default _beer_) for the child.
+
+*BEER_LOG*
+	Log filter, in the _tracing_ env-filter syntax (e.g. _debug_).
+
+# SIGNALS
+
+*SIGUSR1*
+	Reload the configuration file and re-apply it without restarting.
+
+# FILES
+
+_$XDG_CONFIG_HOME/beer/beer.toml_
+	The configuration file (falls back to _~/.config/beer/beer.toml_). See
+	_beer.toml_(5).
+
+# SEE ALSO
+
+_beer.toml_(5)

doc/beer.toml.5.scd

@@ -0,0 +1,114 @@
+beer.toml(5)
+
+# NAME
+
+beer.toml - configuration file for _beer_(1)
+
+# DESCRIPTION
+
+*beer* reads a TOML configuration file from
+_$XDG_CONFIG_HOME/beer/beer.toml_, falling back to
+_~/.config/beer/beer.toml_, or from the path given to *--config*. A missing
+file uses the built-in defaults; a malformed file is reported and the defaults
+are used. Unknown keys are ignored, so a file written for a newer *beer* still
+loads.
+
+Colours are X11 specs: either _#rrggbb_ or _rgb:rr/gg/bb_ (1-4 hex digits per
+channel).
+
+# [main]
+
+*font* = _string_
+	Primary font family, resolved via fontconfig. Default _monospace_.
+
+*font-size* = _integer_
+	Font size in pixels. Default _16_.
+
+*term* = _string_
+	The _TERM_ value exported to the child shell. Default _beer_.
+
+*initial-cols* = _integer_, *initial-rows* = _integer_
+	Initial window size in character cells. Default _80_ by _24_.
+
+*pad-x* = _integer_, *pad-y* = _integer_
+	Inner padding in pixels between the window edge and the cell grid.
+	Default _2_ each.
+
+*word-delimiters* = _string_
+	Characters that break a word for double-click selection. Unset keeps the
+	built-in set (whitespace and common punctuation, keeping _.-/:~\__ inside
+	words).
+
+# [colors]
+
+*foreground* = _color_, *background* = _color_
+	Default text and background colours. Default _#c5c8c6_ on _#181818_.
+
+*cursor* = _color_
+	Cursor colour. Unset follows the cell under the cursor.
+
+*selection-foreground* = _color_, *selection-background* = _color_
+	Selection colours. The background defaults to _#44475a_.
+
+*regular* = _[8 colors]_, *bright* = _[8 colors]_
+	The eight regular (indices 0-7) and bright (8-15) palette entries. Unset
+	entries keep the xterm defaults.
+
+*match-background* = _color_, *match-current-background* = _color_
+	Highlight colours for search matches and the focused match.
+
+*alpha* = _float_
+	Background opacity, _0.0_ (transparent) to _1.0_ (opaque). Default _1.0_.
+
+*bold-as-bright* = _bool_
+	Render bold text with the bright palette variant. Default _true_.
+
+# [cursor]
+
+*style* = _string_
+	Default cursor shape: _block_, _beam_ (or _bar_), or _underline_. An
+	application may override this at runtime via DECSCUSR. Default _block_.
+
+*blink* = _bool_
+	Whether the cursor blinks by default. Default _false_.
+
+# [scrollback]
+
+*lines* = _integer_
+	Lines of history retained for the main screen. Default _10000_.
+
+# [bell]
+
+*visual* = _bool_
+	Briefly flash the screen on the terminal bell. Default _false_.
+
+# [key-bindings]
+
+A table of _chord_ = _action_ entries, merged over the built-in defaults. A
+chord is modifiers and a key joined by _+_, e.g. _"Ctrl+Shift+C"_. An action of
+_"none"_ unbinds the chord.
+
+Recognized actions: _copy_, _paste_, _paste-primary_, _scrollback-up_,
+_scrollback-down_, _scrollback-top_, _scrollback-bottom_, _search_,
+_font-increase_, _font-decrease_, _font-reset_, _fullscreen_.
+
+```
+[key-bindings]
+"Ctrl+Shift+C" = "copy"
+"Ctrl+grave" = "none"
+```
+
+# [text-bindings]
+
+A table of _chord_ = _text_ entries that send a literal string to the shell.
+The text understands the escapes _\\e_, _\\n_, _\\r_, _\\t_, _\\\\_, and
+_\\xNN_.
+
+```
+[text-bindings]
+"Ctrl+Shift+Return" = "\\x1b\\r"
+```
+
+# SEE ALSO
+
+_beer_(1)

nix/package.nix

@@ -4,6 +4,8 @@
   pkg-config,
   makeBinaryWrapper,
   ncurses,
+  scdoc,
+  installShellFiles,
   wayland,
   libxkbcommon,
   freetype,
@@ -24,6 +26,7 @@ rustPlatform.buildRustPackage (finalAttrs: {
         (s + /Cargo.lock)
         (s + /Cargo.toml)
         (s + /terminfo)
+        (s + /doc)
       ];
     };
 
@@ -35,6 +38,8 @@ rustPlatform.buildRustPackage (finalAttrs: {
     pkg-config
     makeBinaryWrapper
     ncurses # tic
+    scdoc # man page generation
+    installShellFiles # installManPage
   ];
 
   buildInputs = [
@@ -49,6 +54,12 @@ rustPlatform.buildRustPackage (finalAttrs: {
   postInstall = ''
     mkdir -p "$out/share/terminfo"
     tic -x -o "$out/share/terminfo" terminfo/beer.info
+
+    # Generate the man pages from their scdoc sources.
+    scdoc < doc/beer.1.scd > beer.1
+    scdoc < doc/beer.toml.5.scd > beer.toml.5
+    installManPage beer.1 beer.toml.5
+
     wrapProgram "$out/bin/beer" \
       --prefix LD_LIBRARY_PATH : ${lib.makeLibraryPath [wayland libxkbcommon]}
   '';

nix/shell.nix

@@ -9,6 +9,7 @@
   cargo-deny,
   pkg-config,
   ncurses,
+  scdoc,
   wayland,
   wayland-protocols,
   wayland-scanner,
@@ -31,6 +32,7 @@ mkShell {
     cargo-deny
     pkg-config
     ncurses # tic, to compile the terminfo entry
+    scdoc # generate man pages from doc/*.scd
   ];
 
   buildInputs = [