4 files changed, 133 insertions(+), 2 deletions(-)

M .gitignore
M Makefile
M README.md
A pustule.1.scd

@@ 1,2 1,3 @@
 pustule
+*.1
 *.o

@@ 1,4 1,4 @@
-all: pustule
+all: pustule pustule.1
 
 CFLAGS ?= -O2
 LDFLAGS ?= -O2


@@ 12,6 12,9 @@ pustule: dyn_array.o events.o lua_mod.o main.o pulse.o argparse/argparse.o log.o
 %.o: %.c pustule.h
 	$(CC) -c -o $@ $< $(CFLAGS) $(DEPS_CFLAGS)
 
+pustule.1: pustule.1.scd
+	scdoc < $< > $@
+
 .PHONY: clean
 clean:
 	rm -f pustule

@@ 26,7 26,8 @@ Tech
 pustule is written in C. It's very lightweight and has few dependencies:
 
 - [PulseAudio][] (specifically libpulse), as it acts as a PulseAudio client
-- [Lua][], a lightweight, extensible programming language.
+- [Lua][], a lightweight, extensible programming language
+- [scdoc][], a simple man page generator (to generate the documentation).
 
 
 Installation


@@ 63,3 64,4 @@ GPLv3+
 
 [Lua]: https://www.lua.org/
 [PulseAudio]: http://www.freedesktop.org/wiki/Software/PulseAudio/
+[scdoc]: https://git.sr.ht/~sircmpwn/scdoc

@@ 0,0 1,125 @@
+pustule(1)
+
+# NAME
+
+pustule - rule-based volume control for PulseAudio
+
+# SYNOPSIS
+
+*pustule* [options...]
+
+# OPTIONS
+
+*-h, --help*
+	Show help message and quit.
+
+*-c, --config* <config>
+	Specifies the path to the config file.
+
+*-d, --debug*
+	Enable debug mode (more verbose logging).
+
+# DESCRIPTION
+
+pustule is a small service that connects to a running PulseAudio daemon and
+applies user-defined configuration rules to inputs and devices (aka _sinks_ and
+_sink inputs_ in PulseAudio-speak). These rules are defined in the Lua
+programming language, making them pretty powerful while still being very
+lightweight.
+
+The provided sample configuration file contains some rules for web browsers and
+media players. The author has also been able to use pustule to have different
+volumes for different kind of notifications when using the Gajim IM client, so a
+much richer configuration is possible.
+
+# CONFIGURATION
+
+If a configuration file is not provided using the *--config* option, pustule
+tries to load _$XDG_CONFIG_HOME/pustule.lua_. If $_XDG_CONFIG_HOME_ is not
+defined, it will look for _$HOME/.config/pustule.lua_ instead.
+
+The configuration file is expected to be a valid Lua script. In addition to the
+Lua standard library, the config script can use the built-in *pustule* module,
+which is described in the *LUA API* section below.
+
+# LUA API
+
+pustule is written with Lua 5.3 compatibility in mind. Other versions may not
+work as expected.
+
+## THE PUSTULE MODULE
+
+pustule exploses its API in the *pustule* module, which can be loaded as any
+standard Lua module:
+
+```
+pustule = require("pustule")
+```
+
+## DATA STRUCTURES
+
+- TODO: inputs
+- TODO: devices
+
+## SIGNALS
+
+Some PulseAudio events are translated into signals. Listeners can be added for
+these signals using the *pustule.connect_signal* function, and removed using
+*pustule.disconnect_signal*.
+
+Functions:
+
+*pustule.connect_signal*(_signal_name_, _callback_)
+	Connect _callback_, a function, to _signal_name_, a string describing a
+	signal. The callback will be called every time that signal is sent.
+	There is no limit on the number of callbacks that can be added to a
+	signal. Callbacks will be called in the order they are added.
+
+*pustule.disconnect_signal*(_signal_name_, _callback_)
+	The opposite: remove an existing _callback_ from the listeners of
+	_signal_name_.
+
+Defined signals, with the arguments passed to their listeners:
+
+*input_added* -> (_index_, _input_)
+	Sent when a new input is added to the PulseAudio daemon, i.e. a new
+	application wants to play some sound. _index_ is the numerical index
+	used by PulseAudio to identify this input, and _input_ is a table
+	containing all the properties that describe this input.
+
+*input_removed* -> (_index_)
+	Sent when an input is removed from the PulseAudio daemon, i.e. an
+	application has stopped playing any sound (or has closed). _index_ is
+	the numerical index used by PulseAudio to identify this input; it's the
+	same as in the *input_added* signal.
+
+*device_added* -> (_index_, _device_)
+	Sent when a new device is added to the PulseAudio daemon: USB or
+	Bluetooth headset, HDMI screen with loudspeakers, etc. _index_ is the
+	numerical index used by PulseAudio to identify this device, and _device_
+	is a table containing all the properties that describe this device.
+
+*device_removed* -> (_index_)
+	Sent when a device is removed from the PulseAudio daemon: USB or
+	Bluetooth headset disconnected, HDMI screen turned off, etc. _index_ is
+	the numerical index used by PulseAudio to identify this device; it's the
+	same as in the *device_added* signal.
+
+## VOLUME CONTROL
+
+- TODO
+
+## HELPERS
+
+- TODO: log functions
+
+# SEE ALSO
+
+- *pulseaudio*(1) and its documentation at
+  https://www.freedesktop.org/wiki/Software/PulseAudio/
+- The Lua language and its documentation at lua.org.
+
+# AUTHORS
+
+Maintained by Thomas Jost <schnouki (at) schnouki (dot) net>. Full sources can
+be found at https://git.sr.ht/~schnouki/pustule.