### changeset 1509:dbb461e55eda

Document tutorial features
author Adam Chlipala Sun, 17 Jul 2011 13:48:00 -0400 d236dbf1b3e3 4aa3b6d962c8 CHANGELOG doc/manual.tex 2 files changed, 27 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- a/CHANGELOG	Sun Jul 17 13:34:41 2011 -0400
+++ b/CHANGELOG	Sun Jul 17 13:48:00 2011 -0400
@@ -1,3 +1,12 @@
+========
+Next
+========
+
+- Start of official tutorial
+- Compiler support for generating nice tutorial HTML from literate source files
+- New protocol 'static' for generating static pages
+- Bug fixes
+
========
20110715
========
--- a/doc/manual.tex	Sun Jul 17 13:34:41 2011 -0400
+++ b/doc/manual.tex	Sun Jul 17 13:48:00 2011 -0400
@@ -293,6 +293,8 @@
The least obvious requirement is setting \texttt{max-procs} to 1, so that lighttpd doesn't try to multiplex requests across multiple external processes.  This is required for message-passing applications, where a single database of client connections is maintained within a multi-threaded server process.  Multiple processes may, however, be used safely with applications that don't use message-passing.

A FastCGI process reads the environment variable \texttt{URWEB\_NUM\_THREADS} to determine how many threads to spawn for handling client requests.  The default is 1.
+
+  \item \texttt{static}: This protocol may be used to generate static web pages from Ur/Web code.  The output executable expects a single command-line argument, giving the URI of a page to generate.  For instance, this argument might be \cd{/main}, in which case a static HTTP response for that page will be written to stdout.
\end{itemize}

\item \texttt{-root Name PATH}: Trigger an alternate module convention for all source files found in directory \texttt{PATH} or any of its subdirectories.  Any file \texttt{PATH/foo.ur} defines a module \texttt{Name.Foo} instead of the usual \texttt{Foo}.  Any file \texttt{PATH/subdir/foo.ur} defines a module \texttt{Name.Subdir.Foo}, and so on for arbitrary nesting of subdirectories.
@@ -306,6 +308,22 @@

There is an additional convenience method for invoking \texttt{urweb}.  If the main argument is \texttt{FOO}, and \texttt{FOO.ur} exists but \texttt{FOO.urp} doesn't, then the invocation is interpreted as if called on a \texttt{.urp} file containing \texttt{FOO} as its only main entry, with an additional \texttt{rewrite all FOO/*} directive.

+\subsection{Tutorial Formatting}
+
+The Ur/Web compiler also supports rendering of nice HTML tutorials from Ur source files, when invoked like \cd{urweb -tutorial DIR}.  The directory \cd{DIR} is examined for files whose names end in \cd{.ur}.  Every such file is translated into a \cd{.html} version.
+
+These input files follow normal Ur syntax, with a few exceptions:
+\begin{itemize}
+\item The first line must be a comment like \cd{(* TITLE *)}, where \cd{TITLE} is a string of your choice that will be used as the title of the output page.
+\item While most code in the output HTML will be formatted as a monospaced code listing, text in regular Ur comments is formatted as normal English text.
In this section, we describe the syntax of Ur, deferring to a later section discussion of most of the syntax specific to SQL and XML.  The sole exceptions are the declaration forms for relations, cookies, and styles.