chiark / gitweb /
Use a local implementation of strptime() instead of broken OS ones
[disorder] / 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
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 <>.
16 .\"
17 .TH disorder_templates 5
19 disorder_templates - DisOrder template file syntax
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.
110 .\" Local Variables:
111 .\" mode:nroff
112 .\" fill-column:79
113 .\" End: