[or-cvs] [tor/master 10/11] Add a comment explaining the doc build system

[nickm@xxxxxxxxxxxxxx]

Author: Nick Mathewson <nickm@xxxxxxxxxxxxxx>
Date: Wed, 20 Jan 2010 23:28:32 -0500
Subject: Add a comment explaining the doc build system
Commit: e407c1adabfa75204d7f68dd66bbb437ea252f25

Updated a little by Sebastian
---
 doc/Makefile.am |   15 +++++++++++++++
 1 files changed, 15 insertions(+), 0 deletions(-)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8619c6f..240646b 100644
--- 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)
-- 
1.6.5