diff --git a/Makefile b/Makefile
index 8fcceef..5a08630 100644
--- a/Makefile
+++ b/Makefile
@@ -15,7 +15,7 @@ ifeq ($(DEBUG),1)
   CFLAGS_DEBUG=-ggdb -DDEBUG
 endif
 
-all: demo demo-async
+all: demo demo-async doc
 
 demo: libtermkey.so demo.c
 	$(CC) $(CFLAGS) $(CFLAGS_DEBUG) -o $@ $^
@@ -29,6 +29,11 @@ libtermkey.so: termkey.o driver-csi.o driver-ti.o
 %.o: %.c termkey.h termkey-internal.h
 	$(CC) $(CFLAGS) $(CFLAGS_DEBUG) -Wall -std=c99 -fPIC -o $@ -c $<
 
+doc: termkey_waitkey.3 termkey_getkey.3
+
+%.3: %.3.sh
+	sh $< >$@
+
 .PHONY: clean
 clean:
 	rm -f *.o demo
diff --git a/termkey_getkey.3 b/termkey_getkey.3.sh
similarity index 91%
rename from termkey_getkey.3
rename to termkey_getkey.3.sh
index f77caa0..1b78948 100644
--- a/termkey_getkey.3
+++ b/termkey_getkey.3.sh
@@ -1,3 +1,5 @@
+# vim:ft=nroff
+cat <<EOF
 .TH TERMKEY_GETKEY 3
 .SH NAME
 termkey_getkey, termkey_getkey_force \- retrieve the next key event
@@ -65,6 +67,14 @@ No key events are ready and the terminal has been closed, so no more will arrive
 .TP
 .B TERMKEY_RES_AGAIN
 No key event is ready yet, but a partial one has been found. This is only returned by \fBtermkey_getkey\fP(). To obtain the partial result even if it never completes, use \fBtermkey_getkey_force\fP().
+.SH EXAMPLE
+The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the termkey instance in a typical \fBpoll\fP()-driven asynchronous program, which may include mixed IO with other file handles.
+.PP
+.in +4n
+`sed i.br demo-async.c`
+.in
+.nf
+.fi
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_advisereadable (3),
@@ -72,3 +82,4 @@ No key event is ready yet, but a partial one has been found. This is only return
 .BR termkey_setwaittime (3),
 .BR termkey_get_keyname (3),
 .BR termkey_snprint_key (3)
+EOF
diff --git a/termkey_waitkey.3 b/termkey_waitkey.3.sh
similarity index 90%
rename from termkey_waitkey.3
rename to termkey_waitkey.3.sh
index 9079dcb..c14bbd7 100644
--- a/termkey_waitkey.3
+++ b/termkey_waitkey.3.sh
@@ -1,3 +1,5 @@
+# vim:ft=nroff
+cat <<EOF
 .TH TERMKEY_WAITKEY 3
 .SH NAME
 termkey_waitkey \- wait for and retrieve the next key event
@@ -23,9 +25,18 @@ A key event as been provided.
 .TP
 .B TERMKEY_RES_EOF
 No key events are ready and the terminal has been closed, so no more will arrive.
+.SH EXAMPLE
+The following example program prints details of every keypress until the user presses "Ctrl-C".
+.PP
+.in +4n
+`sed i.br demo.c`
+.in
+.nf
+.fi
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_getkey (3),
 .BR termkey_setwaittime (3),
 .BR termkey_get_keyname (3),
 .BR termkey_snprint_key (3)
+EOF