Document some known LaTeX idiosyncracies

README.md

@@ -41,7 +41,7 @@ improving this infrastructure.
   behaves oddly, we also recommend `mkdir ~/texmf/tex/latex/dummy` so
   that kpathsea will follow the symlink properly.)
 
-## Usage
+## Building Documents
 
 The top-level `Makefile` in your document's source tree -- remember,
 that's a different tree from this one -- should be a copy of the file
@@ -77,6 +77,44 @@ underscore.
 See the plugins in ./pipeline/plugins for documentation on specific
 plugins.
 
+## LaTeX Usage
+
+Mostly you should just use standard LaTeX in OTS Doctools documents.
+However, there are some things you should know:
+
+### Avoid accidentally triggering jinja
+
+If you start a LaTeX comment using two or more percent signs together
+("%%") at the beginning of a line, then the jinja template parser --
+which runs before LaTeX -- will try to interpret that line as a jinja
+command, usually resulting in an error:
+
+```
+  Traceback (most recent call last):
+    [... long traceback stack here ...]
+  jinja2.exceptions.TemplateSyntaxError: tag name expected
+```
+
+The solution is to just always put a space after the first "%" when
+starting off a LaTeX comment at the beginning of a line:
+
+```
+  %%% This will cause a problem, because the line starts with "%%".
+  
+  % %% But this, on the other hand, will be fine.
+```
+
+### Use `longtable` for tables.
+
+Use the [longtable](https://ctan.org/pkg/longtable) package for
+tables, instead of the default LaTeX tabular environment.  This is
+really a generic recommendation, not specific to OTS Doctools, but
+it's [come up
+before](https://code.librehq.com/ots/ots-doctools/-/issues/2) so we
+thought we'd document it here.  Among other things, if you use
+`longtable`, then in-table footnotes will be [handled
+correctly](https://code.librehq.com/ots/ots-doctools/-/issues/3).
+
 ## Windows
 
 Linux and OS X should generally do the right thing with these