Document disparity between footer.html and themable-footer.html

themes/README.rst

@@ -8,7 +8,7 @@ installation.  You can override Sass and CSS settings, images, or entire HTML
 templates.
 
 Eventually, Comprehensive Theming will obsolete existing theming mechanisms,
-but for now they co-exist peacefully. This document describes how to use 
+but for now they co-exist peacefully. This document describes how to use
 Comprehensive Theming, and also the changes you'll need to make to keep other
 theming mechanisms working.
 
@@ -90,6 +90,28 @@ in the appropriate place, and making the changes you need.  Keep in mind that
 in the future if you upgrade the Open edX code, you may have to update the
 copied template in your theme also.
 
+Template Names
+==============
+
+Here are the list of template names that you *should* use in your comprehensive
+theme (so far):
+
+* ``header.html``
+* ``footer.html``
+
+You should **not** use the following names in your comprehensive theme:
+
+* ``themable-footer.html``
+
+If you look at the ``main.html`` template file, you will notice that it includes
+``header.html`` and ``themable-footer.html``, rather than ``footer.html``.
+You might be inclined to override ``themable-footer.html`` as a result. DO NOT
+DO THIS. ``themable-footer.html`` is an additional layer of indirection that
+is necessary to avoid breaking microsites, which also refers to a file named
+``footer.html``. The goal is to eventually make comprehensive theming do
+everything that microsites does now, and then deprecate and remove microsites
+from the codebase. At that point, the ``themable-footer.html`` file will go
+away, since the additional layer of indirection will no longer be necessary.
 
 Installing your theme
 ---------------------