add docs (manpages, README, etc) and cleanup Makefile

5 files changed, 153 insertions, 24 deletions

diff --git a/.gitignore b/.gitignore
index 64def30..4a29496 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,6 @@
 target/
+doc/*.6
+doc/*.6.gz
 
 *.o
 *.a
diff --git a/Makefile b/Makefile
index 0cb65a1..481ccc3 100644
--- a/Makefile
+++ b/Makefile
@@ -4,27 +4,32 @@
 # This Makefile is self-documenting (via the 'help' target)
 # see: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html
 
-CARGO = cargo
-CARGO_OPTS =
-PREFIX=/usr
-
 HACKS=exuberantbovines
+
+CARGO ?= cargo
+CARGO_OPTS ?=
+PREFIX ?= /usr
+PANDOC ?= pandoc
+PANDOCFLAGS ?=
+MANSECTION = 6
+MANPAGE.md = $(PANDOC) --standalone $(PANDOCFLAGS) --to man
+MANPAGES = $(foreach HACK, $(HACKS), doc/$(HACK).$(MANSECTION))
+MANPAGEZ = $(foreach HACK, $(HACKS), doc/$(HACK).$(MANSECTION).gz)
+
 INSTALL_BIN=$(PREFIX)/lib/xscreensaver
 INSTALL_CONFIG=$(PREFIX)/share/xscreensaver/config
-INSTALL_MAN=$(PREFIX)/share/man
+INSTALL_MAN=$(PREFIX)/share/man/man$(MANSECTION)
 
-all:    ## Alias for build
-	$(MAKE) build
-	$(MAKE) doc
+all: build doc ## Alias for build
 
 build:    ## Compiles the default target
-	$(CARGO) $(CARGO_OPTS) build
+	@$(CARGO) $(CARGO_OPTS) build
 
 build-debug:     ## Compiles for 'debug' target
-	$(CARGO) $(CARGO_OPTS) build --debug
+	@$(CARGO) $(CARGO_OPTS) build --debug
 
 build-release:   ## Compiles for 'release' target
-	$(CARGO) $(CARGO_OPTS) build --release
+	@$(CARGO) $(CARGO_OPTS) build --release
 
 install: build-release doc-release  ## Installs everything!
 	@echo "Installing under $(PREFIX)..."
@@ -32,8 +37,12 @@ install: build-release doc-release  ## Installs everything!
 	sudo mkdir -p $(PREFIX)/share/xscreensaver/config
 	@for PROG in $(HACKS); do \
 		sudo install -m 0755 target/release/$$PROG $(INSTALL_BIN); \
-		sudo install -m 0644 extra/$$PROG.xml $(INSTALL_CONFIG); \
+		sudo install -m 0644 configs/$$PROG.xml $(INSTALL_CONFIG); \
+		sudo install -m 0644 doc/$$PROG.$(MANSECTION).gz $(INSTALL_MAN); \
 	done
+	@echo "Updating mandb (this takes a few seconds)..."
+	@sudo mandb -q
+	@echo ""
 	@echo "IMPORTANT: For the hacks to show up you'll need to add the following lines to ~/.xscreensaver:"
 	@echo "";
 	@for PROG in $(HACKS); do \
@@ -43,23 +52,30 @@ install: build-release doc-release  ## Installs everything!
 	@echo "(don't worry about duplicate lines, xscreensaver will clean that up)"
 
 clean:   ## Deletes intermediate files (including compiled deps)
-	$(CARGO) $(CARGO_OPTS) clean
+	@$(CARGO) $(CARGO_OPTS) clean
+	@rm -f $(MANPAGES) $(MANPAGEZ)
 
-check:   ## Rebuilds and runs tests
-	$(MAKE) build
-	$(MAKE) test
+check: build test   ## Rebuilds and runs tests
 
 test:    ## Runs tests (if they exist)
-	$(CARGO) $(CARGO_OPTS) test
+	@$(CARGO) $(CARGO_OPTS) test
 
 bench:   ## Run benchmarks (if they exist)
-	$(CARGO) $(CARGO_OPTS) bench
+	@$(CARGO) $(CARGO_OPTS) bench
+
+docs: doc
+
+doc: $(MANPAGEZ) ## Builds documentation (if there is any) for the default target
+	@$(CARGO) $(CARGO_OPTS) doc --no-deps
+
+doc-release: $(MANPAGEZ) ## Builds documentation (if there is any) for release
+	@$(CARGO) $(CARGO_OPTS) doc --no-deps --release
 
-doc:     ## Builds documentation (if there is any) for the default target
-	$(CARGO) $(CARGO_OPTS) doc --no-deps
+$(MANPAGES): %.$(MANSECTION): %.$(MANSECTION).md
+	$(MANPAGE.md) $< -o $@
 
-doc-release:     ## Builds documentation (if there is any) for release
-	$(CARGO) $(CARGO_OPTS) doc --no-deps --release
+$(MANPAGEZ): %.$(MANSECTION).gz: %.$(MANSECTION)
+	@gzip --keep --force $<
 
 help:
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-25s\033[0m %s\n", $$1, $$2}'
diff --git a/README.txt b/README.txt
index 1aac5e3..5483263 100644
--- a/README.txt
+++ b/README.txt
@@ -6,9 +6,35 @@
  \___/_/\_\\__,_|_.__/ \___|_|  \__,_|_| |_|\__| |_.__/ \___/ \_/ |_|_| |_|\___||___(_)
 
 
-### Dependencies
 
-Circa June 2016, this requires a patched version of the `glutin` window
+### Build Dependencies and Installation
+
+It should be possible to build this project for most platforms using cargo
+directly. Installation and XScreensaver integration probably only works on UNIX
+machines (Linux, *BSD, etc). It's only been developed and tested on Debian
+jessie, using the stable Rust toolchain (version 1.9).
+
+A patched version of the `glutin` OpenGL window generation library is required;
+see below.
+
+The `pandoc` tool is required for building manpages.
+
+To just build (`--debug`) and run an indivual "hack", eg `exuberantbovines`:
+
+    cargo run --bin exuberantbovines
+
+To build everything (`--release`) and install, first run:
+
+    make install
+
+Then follow the directions about adding lines like the following to you
+`~/.xscreensaver` to have hacks actually show up in, eg, `xscreensaver-demo`:
+
+    GL:               exuberantbovines --root             \n\
+
+### Installing Patched glutin Library
+
+Circa June 2016, this project requires a patched version of the `glutin` window
 creation library to allow re-using an existing X Window. This is only necessary
 for integration with X Windows, but the project won't build without it.
 
@@ -22,3 +48,11 @@ Checkout the `feature-existing` branch from
 
   paths = ["/home/bnewbold/src/glutin"]
 
+### Creating Your Own Hacks
+
+You'll need to create at least three files with the same base name ("$HACK"):
+
+- the rust sourcecode (src/bin/$HACK.rs)
+- an XML config file (configs/$HACK.xml)
+- a manpage in Markdown format (doc/$HACK.6.md)
+
diff --git a/extra/exuberantbovines.xml b/configs/exuberantbovines.xml
index 49bc7d6..49bc7d6 100644
--- a/extra/exuberantbovines.xml
+++ b/configs/exuberantbovines.xml
diff --git a/doc/exuberantbovines.6.md b/doc/exuberantbovines.6.md
new file mode 100644
index 0000000..dd45d0f
--- /dev/null
+++ b/doc/exuberantbovines.6.md
@@ -0,0 +1,77 @@
+% exuberantbovines(6) | XScreenSaver manual
+
+NAME
+====
+
+**exuberantbovines** — rust port of bouncingcow
+
+SYNOPSIS
+========
+
+| **exuberantbovines** \[**-h**|**--help**] \[**--window-id** _id_] \[**--root**]
+| \[**--wireframe**] \[**--fps**]
+
+DESCRIPTION
+===========
+
+This is a "hack" for the XScreensaver screen locker. It shows a bouncing (or at
+least happily oscillating) bovine.
+
+OPTIONS
+=========
+
+_exuberantbovines_ accepts the following options. Note that some long options (like
+**root** and **window-id** can be passed with either a single dash (**-root**)
+or a double-dash (**--root**) for backwards compatibility with XScreensaver.
+
+-h, --help
+
+:   Prints brief usage information.
+
+--wireframe
+
+:   Render in wireframe instead of solid. (UNIMPLEMENTED)
+
+--fps
+
+:   Display the current frame rate, CPU load, and polygon count. (UNIMPLEMENTED)
+
+
+FILES
+=====
+
+*~/.xscreensaver*
+
+:   Per-user configuration file. If there isn't a line for this hack in the
+    file, xscreensaver-demo won't find or run this hack.
+
+*/usr/share/xscreensaver/config/exuberantbovines.xml*
+
+:   Configuration options for this hack
+
+ENVIRONMENT
+===========
+
+**XSCREENSAVER_WINDOW**
+
+:   Optional ID number of the X window to draw into.
+
+Note that **XENVIRONMENT** and **DISPLAY** are *not* implemented.
+
+BUGS
+====
+
+A lot of features (like fps, root-window-finding, wireframe, etc) aren't
+implemented yet.
+
+See GitHub Issues: <https://github.com/bnewbold/exuberant-bovines/issues>
+
+AUTHOR
+======
+
+Bryan Newbold <bnewbold@robocracy.org>
+
+SEE ALSO
+========
+
+**bouncingcow(6)**, **xscreensaver(1)**, **xscreensaver-demo(1)**