Add README.doc.template

etc/Makefile

@@ -40,8 +40,9 @@ appmakefiles: $(APPMAKEFILES)
 
 docs: $(DOCMAKEFILES)
 
-../%/doc/Makefile: Makefile.doc.template Makefile makemake.py
+../%/doc/Makefile: Makefile.doc.template Makefile makemake.py README.doc.template
 	mkdir -p $(dir $@)
+	cp -f README.doc.template $(dir $@)/README
 	(cd $(dir $@)/..; ../../etc/makemake.py --relpath --template ../../etc/Makefile.doc.template . . ../../utils ../../fonts ../../drivers ../../drivers/avr > doc/Makefile)
 
 ../%/Makefile.test: Makefile.test.template Makefile

etc/README.doc.template

@@ -0,0 +1,16 @@
+Running make in this directory will generate a number of PDF graphs.
+In the callgraph, the arrows means "calls".  In the dependency graphs,
+the arrows means "requires" (or "depends upon").
+
+callgraph.pdf             This shows the callgraph, i.e., what functions each
+                          function in the program calls.
+module_dependencies.pdf   This shows the dependencies between the modules.
+file_dependencies.pdf     This shows the dependencies between the files.
+makefile_dependencies.pdf This shows the dependencies required by make when
+                          building the program.
+build_dependencies.pdf    This is like makefile_dependencies.pdf but shows
+                          the operations performed to generate the new file.
+
+callgraph.d               This shows the callgraph in text format.
+files.d                   This shows the file dependencies in text format.
+modules.d                 This shows the module dependencies in text format.

etc/makemake.py

@@ -120,6 +120,11 @@ def file_parse (pathname, indent, debug):
     text = file.read ()
     file.close ()
 
+    # We could use the -MM option for gcc to find all the header file
+    # dependencies (even with conditional compilation) but we would
+    # not find the relationship between the header files.  So let's do
+    # if outselves even with conditional compilation may lead us
+    # astray.
     prog = re.compile (r'^#include[ ].*["<]([a-zA-Z_.0-9].*)[">]', re.MULTILINE)
 
     hfilelist = prog.findall (text, 0)