[PATCH 13/18] doc: explain the publican build process

[Peter Hutterer]

This makefile is a bit hard to read due to some publican requirements and
the need to generate some files through XSLT. Explain the lot, so that those
looking at this roughly know what will hit them.

Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
 doc/Wayland/Makefile.am | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 542636a..13e02d7 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -1,3 +1,20 @@
+# Documentation is built with publican
+# https://fedorahosted.org/publican/
+# Publican takes docbook-style input files and compiles them to various
+# output formats.
+#
+# How this build works:
+# * the main target is Wayland, documentation ends up in $(builddir)/Wayland/
+# * hand-written chapters are located in en_US
+#   Publican does not take a source path, so to support out-of-tree builds
+#   these are copied to $(builddir)/en-US which is the actual directory
+#   Publican uses.
+# * ProtocolSpec.xml is generated from $(top_srcdir)/protocol/wayland.xml,
+#   changed into docbook via XSLT and saved in $(builddir)/en-US/
+# * ProtocolInterfaces.xml, same as above, uses a different XSLT
+# * WaylandClientAPI.xml is generated from the doxygen output and saved in
+#   $(builddir)/en-US
+# * run Publican on en-US
 publican_sources = \
 	$(srcdir)/en_US/Wayland.ent \
 	$(srcdir)/en_US/Wayland.xml \
-- 
1.8.1.4