ttym patches
============

Each patch is a unified diff against the pristine base. Apply with:

    cd ttym
    patch -p1 < patches/ttym-<name>-3.0.diff

Then rebuild:

    rm -f config.h ; make

To get every feature at once, skip the individual patches entirely and
apply ttym-full-3.0.diff -- one combined diff, no conflicts to resolve.
See "The full build" below.


What is in the base
-------------------

The base build is terminal-only: it opens /dev/tty, draws, and exits.
It does not write files, spawn processes or depend on anything outside
libc. That includes the progress-bar styles, the alert loop and the
terminal flash, which were separate patches through 2.0:

  - countdown and stopwatch, pause/resume, quit
  - progress bar with eight built-in styles (--bar, BAR_STYLE)
  - alert-until-keypress on completion (--no-persist, ALERT_PERSIST)
  - reverse-video flash during that alert (--flash, FLASH)

Every remaining patch changes what the program *touches* -- the
filesystem, subprocesses, or external binaries. That is the line the
split is drawn on.


The full build
--------------

  ttym-full-3.0.diff
      Every feature in a single patch: notify, logging, hooks and
      config-file, with all inter-patch conflicts already resolved.
      Apply it to the pristine base and rebuild:

          patch -p1 < patches/ttym-full-3.0.diff
          rm -f config.h ; make

      This is the recommended route to the full-featured build. It is
      equivalent to stacking the four feature patches below and hand-
      resolving every collision, but deterministic and conflict-free.
      Use the individual patches only when you want a specific subset.


Available patches
-----------------

  ttym-notify-3.0.diff
      One-shot desktop notification and sound on countdown completion,
      plus a MESSAGE positional argument piped through {title}/{msg}
      placeholders. Spawns notify-send and a sound player.
      Adds: TITLE, NOTIFY_CMD, SOUND_CMD knobs.

  ttym-logging-3.0.diff
      TSV log at ~/.config/ttym/ttym.log, +tag extraction, the -r
      reader (-n, --raw), and --stats (today|week|month|all). Adds
      one-shot directory migration from ~/.config/timer/.
      Adds: -c TEXT flag.

  ttym-hooks-3.0.diff
      Optional executables at ~/.config/ttym/hooks/{on_start,on_done,
      on_quit} invoked with: mode duration_seconds comment.
      Adds: -c TEXT flag (passed as 3rd hook arg).

  ttym-config-file-3.0.diff                       [requires notify]
      Runtime config read from /etc/ttym.conf, then
      ~/.config/ttym/config (key = value). Exposes eight keys:
      bar_fill, bar_empty, bar_style, flash, alert_persist, title,
      notify_cmd, sound_cmd. Unknown keys and unparseable values are
      reported on stderr. Nothing is written to disk: --dump-config
      prints a commented template on stdout, so a user does

          timer --dump-config > ~/.config/ttym/config

      It needs notify only for the title / notify_cmd / sound_cmd
      keys; the bar and alert keys it exposes now live in the base.


Dependencies
------------

config-file requires notify. Everything else is independent of the
base and of each other.


Stacking
--------

The simplest route to the full build is ttym-full-3.0.diff (see "The
full build" above). The notes here apply only when stacking the
feature patches by hand to assemble a subset.

Every patch in this directory applies and compiles cleanly against the
pristine base -- except config-file, which builds on notify.

Combining multiple optional patches will produce conflicts at shared
regions: the Config struct, usage(), the getopt() option string, and
in some cases #include lines. This is normal suckless territory --
resolve by hand, or apply ttym-full-3.0.diff instead. Two known
collisions when stacking logging with hooks: both own the -c flag, so
keep one Config member and one usage() line for it.

Recommended order when stacking:

    notify  ->  logging  ->  hooks  ->  config-file

config-file must come last -- it overrides the resolved bar glyphs and
extends usage() with lines the other patches also touch. Apply,
resolve any .rej files, rebuild.


Authoring new patches
---------------------

Match the discipline used here:

  - Add compile-time knobs to config.def.h, never inline in ttym.c.
  - Update usage() in the same hunk as the option parser change, so
    `timer -h` never drifts from what the build actually supports.
  - Verify with `patch -p1` against a fresh copy of the base -- or,
    for a patch with prerequisites, the base plus those -- and confirm
    the result compiles before publishing.
  - When the patch set changes, regenerate ttym-full-3.0.diff so the
    one-shot full build stays in sync.