build: rework Makefile for man-page target

This adds `make man` with SRCDIR and BUILDDIR support. This is copied
from *osbuild*. Since `make man` will be the official way to build the
man-pages, lets also import `make help` and some documentation for the
Makefile.

Makefile

@@ -1,4 +1,104 @@
-COMMIT=$(shell git rev-parse HEAD)
+#
+# Maintenance Helpers
+#
+# This makefile contains targets used for development, as well as helpers to
+# aid automatization of maintenance. Unless a target is documented in
+# `make help`, it is not supported and is only meant to be used by developers
+# to aid their daily development work.
+#
+# All supported targets honor the `SRCDIR` variable to find the source-tree.
+# For most unsupported targets, you are expected to have the source-tree as
+# your working directory. To specify a different source-tree, simply override
+# the variable via `SRCDIR=<path>` on the commandline. By default, the working
+# directory is used for build output, but `BUILDDIR=<path>` allows overriding
+# it.
+#
+
+BUILDDIR ?= .
+SRCDIR ?= .
+
+RST2MAN ?= rst2man
+
+#
+# Automatic Variables
+#
+# This section contains a bunch of automatic variables used all over the place.
+# They mostly try to fetch information from the repository sources to avoid
+# hard-coding them in this makefile.
+#
+# Most of the variables here are pre-fetched so they will only ever be
+# evaluated once. This, however, means they are always executed regardless of
+# which target is run.
+#
+#     COMMIT:
+#         This evaluates to the latest git commit sha. This will not work if
+#         the source is not a git checkout. Hence, this variable is not
+#         pre-fetched but evaluated at time of use.
+#
+
+COMMIT = $(shell (cd "$(SRCDIR)" && git rev-parse HEAD))
+
+#
+# Generic Targets
+#
+# The following is a set of generic targets used across the makefile. The
+# following targets are defined:
+#
+#     help
+#         This target prints all supported targets. It is meant as
+#         documentation of targets we support and might use outside of this
+#         repository.
+#         This is also the default target.
+#
+#     $(BUILDDIR)/
+#     $(BUILDDIR)/%/
+#         This target simply creates the specified directory. It is limited to
+#         the build-dir as a safety measure. Note that this requires you to use
+#         a trailing slash after the directory to not mix it up with regular
+#         files. Lastly, you mostly want this as order-only dependency, since
+#         timestamps on directories do not affect their content.
+#
+
+.PHONY: help
+help:
+	@echo "make [TARGETS...]"
+	@echo
+	@echo "This is the maintenance makefile of osbuild. The following"
+	@echo "targets are available:"
+	@echo
+	@echo "    help:               Print this usage information."
+	@echo "    man:                Generate all man-pages"
+
+$(BUILDDIR)/:
+	mkdir -p "$@"
+
+$(BUILDDIR)/%/:
+	mkdir -p "$@"
+
+#
+# Documentation
+#
+# The following targets build the included documentation. This includes the
+# packaged man-pages, but also all other kinds of documentation that needs to
+# be generated. Note that these targets are relied upon by automatic
+# deployments to our website, as well as package manager scripts.
+#
+
+MANPAGES_RST = $(wildcard $(SRCDIR)/docs/*.[0123456789].rst)
+MANPAGES_TROFF = $(patsubst $(SRCDIR)/%.rst,$(BUILDDIR)/%,$(MANPAGES_RST))
+
+$(MANPAGES_TROFF): $(BUILDDIR)/docs/%: $(SRCDIR)/docs/%.rst | $(BUILDDIR)/docs/
+	$(RST2MAN) "$<" "$@"
+
+.PHONY: man
+man: $(MANPAGES_TROFF)
+
+#
+# Maintenance Targets
+#
+# The following targets are meant for development and repository maintenance.
+# They are not supported nor is their use recommended in scripts.
+#
 
 .PHONY: build
 build: