diff --git a/README.txt b/README.txt
index 6e3677f..55477bb 100755
--- a/README.txt
+++ b/README.txt
@@ -1,6 +1,5 @@
-SETUP
-
-Required environment variables:
+Required environment variables
+==============================
 
 TEACHING_SHARED
 This variable specifies the path to the top level of the teaching shared
@@ -20,7 +19,7 @@
 This variable specifies the path to the top level directory on the web
 server, under which the files for this paper will be installed (that is,
 the directory that contains the individual paper directory hierarchies).
-Under Windows this would typically point to \\INFO-NTS-12\DBCourses$
+Under Windows this would typically point to "\\INFO-NTS-12\DBCourses$"
 (but this may require munging depending on how UNC paths are dealt
 with). On my machine this is set to "/Volumes/DBCOURSES$", because this
 is where the share gets mounted.
@@ -31,3 +30,37 @@
 implementation of Xalan and "xalan-j" for the Java implementation of
 Xalan (weirdly, the latter two have different command line options). For
 example, on my machine this is set to "saxon".
+
+
+Including content files
+=======================
+
+To simulate the effect of XML fragment inclusion (which isn't supported
+in any software yet), we use ASP like tags in the document files to mark where content
+files should be inserted. These tags look something like this:
+
+<@INC[DBMS/Q_What_is_a_DBMS.xml]@>
+
+What the makefile does is run a Perl script to replace each of these
+tags with the content of the file specified by the include path (this
+path is relative to the root directory of the paper + the section name,
+e.g., $(ALL_PAPERS_ROOT)/INFO212/Tutorials).
+
+A problem can arise if one of these tags occurs inside an XML comment, e.g.:
+
+<!--
+	<@INC[DBMS/Q_What_is_a_DBMS.xml]@>
+-->
+
+This is a problem if the content file Q_What_is_a_DBMS.xml also contains
+XML comments. Comments cannot be nested in XML, and the XSLT processor
+will complain bitterly. The solution is to "neuter" the include tag, by
+changing it in such a way that the Perl script will no longer recognise
+it, e.g.:
+
+<!--
+	<@IN[DBMS/Q_What_is_a_DBMS.xml]@>
+-->
+
+Just remember to change it back when you un-comment the inclusion, or
+the XSLT processor will complain about malformed XML tags :)