Mercurial > urweb

comparison doc/manual.tex @ 1509:dbb461e55eda

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Document tutorial features
author Adam Chlipala <adam@chlipala.net>
date Sun, 17 Jul 2011 13:48:00 -0400
parents a77fa7e7bb7b
children 8c65218920cf
comparison
equal deleted inserted replaced
1508:d236dbf1b3e3 1509:dbb461e55eda
291 ) 291 )
292 \end{verbatim} 292 \end{verbatim}
293 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. 293 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.
294 294
295 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. 295 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.
296
297 \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.
296 \end{itemize} 298 \end{itemize}
297 299
298 \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. 300 \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.
299 301
300 \item \texttt{-sigfile PATH}: Same as the \texttt{sigfile} directive in \texttt{.urp} files 302 \item \texttt{-sigfile PATH}: Same as the \texttt{sigfile} directive in \texttt{.urp} files
303 305
304 \item \texttt{-static}: Link the runtime system statically. The default is to link against dynamic libraries. 306 \item \texttt{-static}: Link the runtime system statically. The default is to link against dynamic libraries.
305 \end{itemize} 307 \end{itemize}
306 308
307 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. 309 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.
310
311 \subsection{Tutorial Formatting}
312
313 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.
314
315 These input files follow normal Ur syntax, with a few exceptions:
316 \begin{itemize}
317 \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.
318 \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.
319 \item A comment like \cd{(* * HEADING *)} introduces a section heading, with text \cd{HEADING} of your choice.
320 \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.
321 \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 *)}.
322 \end{itemize}
323
324 A word of warning: as for demo generation, tutorial generation calls Emacs to syntax-highlight Ur code.
325
308 326
309 \section{Ur Syntax} 327 \section{Ur Syntax}
310 328
311 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. 329 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.
312 330