Changeset 45af145fba9488de1cc9d7106aaa6061d101fe2b for doc

Timestamp:

01/02/10 18:28:55 (2 years ago)

Author:

Antti-Juhani Kaijanaho <antti-juhani@…>

Children:

cc0a570a9262613f7046938be649f27646987cb8

Parents:

71574e315e6b251c23a07e6e591cec8ddbc01261

git-committer:

Antti-Juhani Kaijanaho <antti-juhani@…> (01/02/10 18:28:55)

Message:

Work on the manual.

Signed-off-by: Antti-Juhani Kaijanaho <antti-juhani@…>

Files:

• doc/alue.texinfo (modified) (11 diffs)

doc/alue.texinfo

@@ -264 +264 @@
 * Conditionals::                
 * Definitions::                 
+* File inclusion::              
 @end menu
 
@@ -316 +317 @@
 directives, a template block is saved (uninterpreted) for late use.
 
+The following example demonstrates the interplay between literal
+material, directive material and template blocks:
+@example
+$if user.logged_in$@{
+  Welcome, $user.name$!
+@}$else$@{
+  Please log in.
+@}
+@end example
+Note that there is no whitespace between curly brackets and the dollar
+signs.  Since the curly brackets are in literal material, any
+surrounding whitespace is significant, and thus writing
+@c
+@samp{$ @{}
+@c
+would break the syntax.
+
+In the example, the following material is literal:
+@itemize @bullet
+@item
+@samp{Welcome, }
+@item
+@samp{!}
+@item
+@samp{Please log in.}
+@end itemize
+as well as all the line breaks and all the indenting whitespace.
+The following material is directive:
+@itemize @bullet
+@item
+@samp{if user.logged_in}
+@item
+@samp{user.name}
+@item
+@samp{else}
+@end itemize
+
+Technically, the dollar signs and the curly brackets ought to be
+categorized as well, but that would be a rather pointless exercise in
+pedantry.@footnote{The dollar signs belong in whatever material that
+precedes them, and the curly brackets are literal.  ---Yes, I'm a
+pedant. Why do you ask?}
+
 @node Values, Expressions, Lexical considerations, The template language
 @subsection Values
 
-Alue provides to a template @dfn{values} in named @dfn{attributes}.  The
+Alue provides a template @dfn{values} in named @dfn{attributes}.  The
 attributes that are defined, and the structure of their values, depends
 on what document the template is producing.  The following kinds of
@@ -340 +384 @@
 Also, a @dfn{closure} is a value (whose textual representation is
 empty), but it arises only from a definition in the template itself.
+
+For examples of the various types, please refer to the sections
+describing individual templates.
 
 @node Expressions, Iterations, Values, The template language
@@ -348 +395 @@
 @dfn{expressions}, and each of them results in a @dfn{value}.  When an
 expression occurs alone, a textual representation of its value is copied
-to the output.  The following kinds of expressions exist.
+to the output.
+
+The following kinds of expressions exist.
 @itemize @bullet
 @item
@@ -372 +421 @@
 @end itemize
 
+For example, to refer to the display name of the currently logged in
+user, one would write (in any template) @samp{authn.user.display-name}.
+Here, @samp{authn} is an attribute reference, while @samp{authn.user}
+and @samp{auth.user.display-name} are subattribute references. The
+expression should be surrounded by dollar signs if it occurs by itself
+among literal material.
+
+For an example of an invocation, @xref{Definitions}.
+
 @node Iterations, Conditionals, Expressions, The template language
 @subsection Iterations
@@ -388 +446 @@
 a template block (the @dfn{body}).
 @end itemize
-Note that the template block's opening curly bracket must come
-immediately after the sequence expression, save for only the dollar
-sign, if one is needed to switch from directive to literal material.
-Specifically, no whitespace is allowed between the dollar sign (or, if
-absent, the end of the expression) and the opening curly bracket.
 
 If the sequence has a sequential value, the behaviour of an iteration
@@ -399 +452 @@
 Otherwise, the iteration directive is ignored.
 
+In the index template, one would produce a listing of all groups with
+something like this:
+@example
+<ul>
+$for group in groups$@{
+  <li>$group.name$ &ndash; $group.description$</li>
+@}
+</ul>
+@end example
+Note well: there is no (and should never be any) whitespace between the
+dollar sign and the opening curly bracket.
+
 @node Conditionals, Definitions, Iterations, The template language
 @subsection Conditionals
@@ -423 +488 @@
 @end itemize
 @end itemize
-Note that each template block's opening curly bracket must come
-immediately after the preceding material, save for only the dollar sign,
-if one is needed to switch from directive to literal material.
-Specifically, no whitespace is allowed between any dollar sign and the
-opening curly bracket.
 
 The behaviour of a conditional directive is determined by the value of
@@ -440 +500 @@
 @end itemize
 
-@node Definitions,  , Conditionals, The template language
+The template fragment
+@example
+$if authn.user$@{
+  Welcome, $authn.user.display-name$!
+@}$else$@{
+  Please log in.
+@}
+@end example
+will copy @samp{Welcome, Antti-Juhani Kaijanaho!} to the output if I am
+logged in, and @samp{Please log in.} if nobody is logged in.
+
+Note well: there is no (and should never be any) whitespace between the
+dollar sign and the curly bracket.
+
+@node Definitions, File inclusion, Conditionals, The template language
 @subsection Definitions
 
-A @dfn{conditional directive} consists of
+A @dfn{definition directive} consists of
 @itemize @bullet
 @item
@@ -458 +532 @@
 a template block (the @dfn{body}).
 @end itemize
-Note that the template block's opening curly bracket must come
-immediately after the preceding material, save for only the dollar sign,
-if one is needed to switch from directive to literal material.
-Specifically, no whitespace is allowed between any dollar sign and the
-opening curly bracket.
 
 A definition makes the function name be defined for the remainder of the
@@ -479 +548 @@
 Definitions may be self-recursive; mutual recursion is not possible.
 
+For example, one might define a function to produce one item in a list
+of messages, including a sublist of the message's follow-ups, as
+follows:
+@example
+$def show_article(article)$@{
+  <li>
+    $article.subject$ by $article.from$
+    $if article.followups$@{
+      <ul>
+        $for art in article.followups$@{
+          $show_article(art)$
+        @}
+      </ul>
+    @}
+  </li>
+@}
+@end example
+
 Note that the body of the definition sees the environment of the
 definition, not the environment of the invocation.  Thus, definitions
-follow the lexical (aka static) scoping discipline.
+follow the lexical (aka static) scoping discipline.  In the example,
+this means that a recursive invocation of @samp{show_article} never has
+direct access to its invoker's @samp{art}.
+
+Note well: there is no (and should never be any) whitespace between the
+dollar sign and the curly bracket.
+
+@node File inclusion,  , Definitions, The template language
+@subsection File inclusion
+
+A @dfn{file inclusion directive} consists of
+@itemize @bullet
+@item
+the reserved word @code{include}, followed by
+@item
+a sequence consisting of ASCII letters (in either case), ASCII decimal
+digits, the dash, the underscore and the period (the @dfn{file name}).
+@end itemize
+
+The effect of a file inclusion directive is to read the named file and
+process it as if it had occurred immediately after the inclusion
+directive, with one difference: the file will be assumed to start with
+literal material.  Once the included file has been processed, the
+including file will continue to be processed as directive material.
+
+File inclusion is a powerful method for structuring templates.  It is,
+for example, useful to write a single file containing the HTML
+preliminaries, and include it in every template.  The included file can
+be parametrized by defining functions in the including file.  For
+example:
+@example
+$def title()$@{$group.name$ threads@}
+$include prelim.inc$
+@end example
+The @file{prelim.inc} file can access the defined title by invoking the
+defined function:
+@example
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE html 
+     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+  <head>
+    <title>$title()$</title>
+  </head>
+  <body>
+  <h1>$title()$</h1>
+@end example
 
 @node GNU General Public License,  , Templates, Top