chiark - git - mdw - disorder/blob - doc/disorder_templates.5.head

   1 .\"
   2 .\" Copyright (C) 2008 Richard Kettlewell
   3 .\"
   4 .\" This program is free software; you can redistribute it and/or modify
   5 .\" it under the terms of the GNU General Public License as published by
   6 .\" the Free Software Foundation; either version 2 of the License, or
   7 .\" (at your option) any later version.
   8 .\"
   9 .\" This program is distributed in the hope that it will be useful, but
  10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12 .\" General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public License
  15 .\" along with this program; if not, write to the Free Software
  16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  17 .\" USA
  18 .\"
  19 .TH disorder_templates 5
  20 .SH NAME
  21 disorder_templates - DisOrder template file syntax
  22 .SH DESCRIPTION
  23 DisOrder template files are text files containing HTML documents, with an
  24 expansion syntax to enable data supplied by the implementation to be inserted.
  25 .SS "Expansion Syntax"
  26 An expansion starts with an at ("@") symbol and takes the form of an expansion
  27 name followed by zero or more arguments.
  28 .PP
  29 Expansion names may contain letters, digits or "-" (and must start with a
  30 letter or digit).  No spacing is allowed between the "@" and the expansion
  31 name.
  32 .PP
  33 Each argument is bracketed.  Any of "(" and ")", "[" and "]" or "{" and "}" may
  34 be used but all arguments for a given expansion must use the same bracket pair.
  35 .PP
  36 Arguments may be separated from one another and the expansion name by
  37 whitespace (including newlines and even completely blank lines).  The parser
  38 always reads as many arguments as are available, even if that is more than the
  39 expansion name can accept (so if an expansion is to be followed by an open
  40 bracket of the same kind it uses, you must use the \fB@_\fR separator; see
  41 below).
  42 .PP
  43 Arguments are expanded within themselves following the same rules, with a few
  44 exceptions discussed below.
  45 .SS "Special Symbols"
  46 A few sequences are special:
  47 .TP
  48 .B @@
  49 This expands to a single "@" sign.
  50 .TP
  51 .B @#
  52 This expands to nothing, and moreover removes the rest of the line it appears
  53 on and its trailing newline.  It is intended to be used as a comment market but
  54 can also be used to eliminate newlines introduced merely to keep lines short.
  55 .TP
  56 .B @_
  57 This expands to nothing (but does not have the line-eating behaviour of
  58 \fB@#\fR).  It is intended to be used to mark the end of an expansion where
  59 that would otherwise be ambiguous.
  60 .SS "Macros"
  61 It is possible to define new expansions using the \fB@define\fR expansion.  For
  62 example,
  63 .PP
  64 .nf
  65 @define{reverse}{a b}{@b @a}
  66 .fi
  67 .PP
  68 defines an expansion called \fB@reverse\fR which expands to its two arguments
  69 in reversed order.  The input \fB@reverse{this}{that}\fR would therefore expand
  70 to "that this".
  71 .SS "Sub-Expansions"
  72 Many expansions expand their argument with additional expansions defined.  For
  73 example, the \fB@playing\fR expansion expands its argument with the extra
  74 expansion \fB@id\fR defined as the ID of the playing track.
  75 .PP
  76 The scope of these sub-expansions is purely lexical.  Therefore if you invoke a
  77 macro or include another template file, if the sub-expansions appear within it
  78 they will not be expanded.
  79 .PP
  80 In the case of a macro you can work around this by passing the value as an
  81 argument.  Included files do not have arguments, so in this case you must
  82 rewrite the inclusion as a macro.
  83 .SS macros.tmpl
  84 Before any page is expanded, the CGI will process \fBmacros.tmpl\fR (and
  85 discard any output).  This defines a collection of commonly used macros.
  86 .SH EXPANSIONS
  87 This section lists the supported expansions.
  88 .\" Local Variables:
  89 .\" mode:nroff
  90 .\" fill-column:79
  91 .\" End:
  92