From af11a6e1e9ebccdcdace2a6df619355b85494d74 Mon Sep 17 00:00:00 2001
From: Nelo Mitranim <me@mitranim.com>
Date: Thu, 26 Oct 2023 12:49:53 +0200
Subject: [PATCH] readme: explain configuration, scripting, more gotchas

---
 gow_term.go | 10 ++++++++++
 readme.md   | 42 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/gow_term.go b/gow_term.go
index c89bfa8..5ed4be6 100644
--- a/gow_term.go
+++ b/gow_term.go
@@ -65,6 +65,16 @@ func (self *TermState) Deinit() {
 	}
 }
 
+/*
+Goal:
+
+	* Get old terminal state.
+	* Compute and set new terminal state.
+	* Remember old terminal state to restore it when exiting.
+
+Known issue: race condition between multiple concurrent `gow` processes in the
+same terminal tab. This is common when running `gow` recipes in a makefile.
+*/
 func (self *TermState) Init(main *Main) {
 	self.Deinit()
 
diff --git a/readme.md b/readme.md
index b481c97..1a772ad 100644
--- a/readme.md
+++ b/readme.md
@@ -11,6 +11,8 @@ Currently requires Unix (MacOS, Linux, BSD). On Windows, runs under WSL.
 * [Installation](#installation)
 * [Usage](#usage)
 * [Hotkeys](#hotkeys)
+* [Configuration](#configuration)
+* [Scripting](#scripting)
 * [Gotchas](#gotchas)
 * [Watching Templates](#watching-templates)
 * [Alternatives](#alternatives)
@@ -97,9 +99,43 @@ Supported control codes with commonly associated hotkeys. Exact keys may vary be
 
 In slightly more technical terms, `gow` switches the terminal into [raw mode](https://en.wikibooks.org/wiki/Serial_Programming/termios), reads from stdin, interprets some ASCII control codes, and forwards the other input to the subprocess as-is. In raw mode, pressing one of these hotkeys causes a terminal to write the corresponding byte to stdin, which is then interpreted by `gow`. This can be disabled with `-r=false`.
 
+## Configuration
+
+At present, `gow` _does not_ support config files. All configuration is done through CLI flags. This is suitable for small, simple projects. Larger projects typically use a build tool such as Make, which is also sufficient for managing the configuration of `gow`. See the example [`makefile`](makefile).
+
+## Scripting
+
+`gow` invokes an arbitrary executable; by default it invokes `go` which should be installed globally. For some advanced use cases, you may need a custom script. For example, if you want `gow` to run `go generate` before any other `go` operation, create a local shell script `go.sh`:
+
+```sh
+touch go.sh
+chmod +x go.sh
+```
+
+...with the following content:
+
+```sh
+#!/bin/sh
+
+go generate &&
+go $@
+```
+
+To invoke it, use `-g` when running `gow`:
+
+```sh
+gow -g=./go.sh -v -c run .
+```
+
+Alternatively, instead of creating script files, you can write recipes in a makefile; see [Configuration](#configuration) and the example [`makefile`](makefile).
+
 ## Gotchas
 
-By default, `gow` expects to be a foreground process in an interactive terminal. When running `gow` as a background process, in Docker, or in any other non-interactive environment, you may see errors related to terminal state. To avoid the problem, run `gow` with `-r=false`. This also disables hotkey support. Examples of such errors:
+By default, `gow` tries to switch the terminal into "raw mode"; see [1](https://en.wikibooks.org/wiki/Serial_Programming/termios). This allows to support hotkeys, but causes issues in the cases listed below. To disable this, run `gow` with `-r=false`, which also disables hotkey support.
+
+### Gotcha: non-interactive environment
+
+By default, `gow` expects to be a foreground process in an interactive terminal. When running `gow` as a background process, in Docker, or in any other non-interactive environment, you may see errors related to terminal state. Examples of such errors:
 
 ```
 > unable to read terminal state
@@ -107,6 +143,10 @@ By default, `gow` expects to be a foreground process in an interactive terminal.
 > operation not supported by device
 ```
 
+### Gotcha: concurrent instances of `gow` in one terminal
+
+There should be only one `gow -r=true` per terminal tab. When running multiple `gow` processes in one terminal tab, most should be `gow -r=false`. `gow` processes do not coordinate. If several are attempting to modify the terminal state (from cooked mode to raw mode, then restore), due to a race condition, they may end up "restoring" the wrong state, leaving the terminal in the raw mode at the end.
+
 ## Watching Templates
 
 Many Go programs, such as servers, include template files, and want to recompile those templates on change.