Add a comment explaining the doc build system

Updated a little by Sebastian

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8619c6f94ade39c02dff1521d75a4b32a34de044..240646b858d462be76ce3ee57b8ed5c82199b36a 100644 (file)
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,18 @@
+
+# We use a two-step process to generate documentation from asciidoc files.
+#
+# First, we use asciidoc/a2x to process the asciidoc files into .1.in and
+# .html.in files (see the asciidoc-helper.sh script). These are the same as
+# the regular .1 and .html files, except that they still have some autoconf
+# variables set in them.
+#
+# Second, we use config.status to turn .1.in files into .1 files and
+# .html.in files into .html files.
+#
+# We do the steps in this order so that we can ship the .*.in files as
+# part of the source distribution, so that people without asciidoc can
+# just use the .1 and .html files.
+
 asciidoc_files = tor tor-gencert tor-resolve torify
 
 html_in = $(asciidoc_files:=.html.in)