# HG changeset patch # User Adam Chlipala # Date 1310924880 14400 # Node ID dbb461e55edae36ea9ab60c69322d1e784a6c591 # Parent d236dbf1b3e3dd31c8ee9998f4ae489a506d0261 Document tutorial features diff -r d236dbf1b3e3 -r dbb461e55eda CHANGELOG --- 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 ======== diff -r d236dbf1b3e3 -r dbb461e55eda doc/manual.tex --- 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. +\item A comment like \cd{(* * HEADING *)} introduces a section heading, with text \cd{HEADING} of your choice. +\item To include both a rendering of an Ur expression and a pretty-printed version of its value, bracket the expression with \cd{(* begin eval *)} and \cd{(* end *)}. The result of expression evaluation is pretty-printed with \cd{show}, so the expression type must belong to that type class. +\item To include code that should not be shown in the tutorial (e.g., to add a \cd{show} instance to use with \cd{eval}), bracket the code with \cd{(* begin hide *)} and \cd{(* end *)}. +\end{itemize} + +A word of warning: as for demo generation, tutorial generation calls Emacs to syntax-highlight Ur code. + + \section{Ur Syntax} 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.