# HG changeset patch
# User Adam Chlipala <adam@chlipala.net>
# Date 1406381985 14400
# Node ID 336070df8aec2caf8690fbbac6ae0d1e5fa09a79
# Parent  ec7a1fa5e88f63ffdd0833f26ca53f7d05724a32
Manual: Heuristic compilation warning

diff -r ec7a1fa5e88f -r 336070df8aec doc/manual.tex
--- a/doc/manual.tex	Sat Jul 26 09:26:11 2014 -0400
+++ b/doc/manual.tex	Sat Jul 26 09:39:45 2014 -0400
@@ -377,6 +377,10 @@
   \item \cd{URWEB\_PQ\_CON}: when using PostgreSQL, overrides the compiled-in connection string
 \end{itemize}
 
+\subsection{A Word of Warning on Heuristic Compilation}
+
+For server-side code, Ur/Web follows an unusual compilation model, where not all type-correct programs can be compiled successfully, especially when using functions as data not known until runtime.  See Section \ref{phases} for more detail.
+
 
 \section{Ur Syntax}
 
@@ -2555,9 +2559,9 @@
 When no \texttt{jsFunc} directive is present, the function is assumed to map to a JavaScript function of the same name, if used in a client-side context.
 
 
-\section{Compiler Phases}
-
-The Ur/Web compiler is unconventional in that it relies on a kind of \emph{heuristic compilation}.  Not all valid programs will compile successfully.  Informally, programs fail to compile when they are ``too higher order.''  Compiler phases do their best to eliminate different kinds of higher order-ness, but some programs just won't compile.  This is a trade-off for producing very efficient executables.  Compiled Ur/Web programs use native C representations and require no garbage collection.
+\section{\label{phases}Compiler Phases}
+
+The Ur/Web compiler is unconventional in that it relies on a kind of \emph{heuristic compilation}.  Not all valid programs will compile successfully.  Informally, programs fail to compile when they are ``too higher order.''  Compiler phases do their best to eliminate different kinds of higher order-ness, but some programs just won't compile.  This is a trade-off for producing very efficient executables.  Compiled Ur/Web programs use native C representations and require no garbage collection.  Also, this warning only applies to server-side code, as client-side code runs in a normal JavaScript environment with garbage collection.
 
 In this section, we step through the main phases of compilation, noting what consequences each phase has for effective programming.