From 206449a95d1a8291dcf4973213976f47508d57dd Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Thu, 25 Jun 2026 11:12:25 +0300 Subject: [PATCH] doc: generate manpages with scdoc Signed-off-by: NotAShelf Change-Id: I76a1ac451259af5b4eb86a609b367ca36a6a6964 --- doc/beer.1.scd | 92 +++++++++++++++++++++++++++++++++++ doc/beer.toml.5.scd | 114 ++++++++++++++++++++++++++++++++++++++++++++ nix/package.nix | 11 +++++ nix/shell.nix | 2 + 4 files changed, 219 insertions(+) create mode 100644 doc/beer.1.scd create mode 100644 doc/beer.toml.5.scd diff --git a/doc/beer.1.scd b/doc/beer.1.scd new file mode 100644 index 0000000..149e753 --- /dev/null +++ b/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) diff --git a/doc/beer.toml.5.scd b/doc/beer.toml.5.scd new file mode 100644 index 0000000..3395eac --- /dev/null +++ b/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) diff --git a/nix/package.nix b/nix/package.nix index b844618..9066551 100644 --- a/nix/package.nix +++ b/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]} ''; diff --git a/nix/shell.nix b/nix/shell.nix index 42d7b73..424960b 100644 --- a/nix/shell.nix +++ b/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 = [