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 3 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,
  10 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\" GNU 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, see <http://www.gnu.org/licenses/>.
  16 .\"
  17 .TH disorder_templates 5
  18 .SH NAME
  19 disorder_templates - DisOrder template file syntax
  20 .SH DESCRIPTION
  21 DisOrder template files are text files containing HTML documents, with an
  22 expansion syntax to enable data supplied by the implementation to be inserted.
  23 .SS "Expansion Syntax"
  24 An expansion starts with an at ("@") symbol and takes the form of an expansion
  25 name followed by zero or more arguments.
  26 .PP
  27 Expansion names may contain letters, digits or "-" (and must start with a
  28 letter or digit).
  29 No spacing is allowed between the "@" and the expansion name.
  30 .PP
  31 Each argument is bracketed
  32 Any of "(" and ")", "[" and "]" or "{" and "}" may be used but all arguments
  33 for a given expansion must use the same bracket pair.
  34 .PP
  35 Arguments may be separated from one another and the expansion name by
  36 whitespace (including newlines and even completely blank lines).
  37 The parser always reads as many arguments as are available, even if that is
  38 more than the expansion name can accept (so if an expansion is to be followed
  39 by an open bracket of the same kind it uses, you must use the \fB@_\fR
  40 separator; see below).
  41 .PP
  42 Arguments are expanded within themselves following the same rules, with a few
  43 exceptions discussed below.
  44 .SS "Special Symbols"
  45 A few sequences are special:
  46 .TP
  47 .B @@
  48 This expands to a single "@" sign.
  49 .TP
  50 .B @#
  51 This expands to nothing, and moreover removes the rest of the line it appears
  52 on and its trailing newline.
  53 It is intended to be used as a comment market but can also be used to eliminate
  54 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).
  59 It is intended to be used to mark the end of an expansion where that would
  60 otherwise be ambiguous.
  61 .SS "Macros"
  62 It is possible to define new expansions using the \fB@define\fR expansion.  For
  63 example,
  64 .PP
  65 .nf
  66 @define{reverse}{a b}{@b @a}
  67 .fi
  68 .PP
  69 defines an expansion called \fB@reverse\fR which expands to its two arguments
  70 in reversed order.
  71 The input \fB@reverse{this}{that}\fR would therefore expand to "that this".
  72 .SS "Sub-Expansions"
  73 Many expansions expand their argument with additional expansions defined.
  74 For example, the \fB@playing\fR expansion expands its argument with the extra
  75 expansion \fB@id\fR defined as the ID of the playing track.
  76 .PP
  77 The scope of these sub-expansions is purely lexical.
  78 Therefore if you invoke a macro or include another template file, if the
  79 sub-expansions appear within it they will not be expanded.
  80 .PP
  81 In the case of a macro you can work around this by passing the value as an
  82 argument.
  83 Included files do not have arguments, so in this case you must rewrite the
  84 inclusion as a macro.
  85 .SS "Search Path"
  86 All template files are first searched for in \fIpkgconfdir\fR and then in
  87 \fIpkgdatadir\fR.
  88 .SS "macros.tmpl and user.tmpl"
  89 Before any template is expanded, the CGI will process \fBmacros.tmpl\fR and
  90 discard any output.
  91 This defines a collection of commonly used macros.
  92 .PP
  93 Following this the CGI will process \fBuser.tmpl\fR, again discarding output.
  94 This can be used to override the common macros without editing the installed
  95 version of \fBmacros.tmpl\fR, or to define new ones.
  96 .PP
  97 It is not an error if \fBuser.tmpl\fR does not exist.
  98 .SS "Character Encoding"
  99 The CGI does not (currently) declare any character encoding.
 100 This could be changed quite easily but in practice is not a pressing necessity.
 101 .PP
 102 The recommended approach is to treat the templates as ASCII files and if
 103 non-ASCII characters are required, use HTML entities to represent them.
 104 .PP
 105 For example, to represent the copyright sign, use \fB&copy;\fR or \fB&#xA9;\fR.
 106 .PP
 107 If you know the decimal or hex unicode value for a character then you can use
 108 \fB&#NNN;\fR or \fB&#xHHHH;\fR respectively.
 109 .SH EXPANSIONS
 110 .\" Local Variables:
 111 .\" mode:nroff
 112 .\" fill-column:79
 113 .\" End:
 114