Commit | Line | Data |
---|---|---|
3e1616b6 RK |
1 | .\" |
2 | .\" Copyright (C) 2008 Richard Kettlewell | |
3 | .\" | |
e7eb3a27 | 4 | .\" This program is free software: you can redistribute it and/or modify |
3e1616b6 | 5 | .\" it under the terms of the GNU General Public License as published by |
e7eb3a27 | 6 | .\" the Free Software Foundation, either version 3 of the License, or |
3e1616b6 | 7 | .\" (at your option) any later version. |
e7eb3a27 RK |
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 | .\" | |
3e1616b6 | 14 | .\" You should have received a copy of the GNU General Public License |
e7eb3a27 | 15 | .\" along with this program. If not, see <http://www.gnu.org/licenses/>. |
3e1616b6 RK |
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 | |
daf0351f RK |
28 | letter or digit). |
29 | No spacing is allowed between the "@" and the expansion name. | |
3e1616b6 | 30 | .PP |
daf0351f RK |
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. | |
3e1616b6 RK |
34 | .PP |
35 | Arguments may be separated from one another and the expansion name by | |
daf0351f RK |
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). | |
3e1616b6 RK |
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 | |
daf0351f RK |
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. | |
3e1616b6 RK |
55 | .TP |
56 | .B @_ | |
57 | This expands to nothing (but does not have the line-eating behaviour of | |
daf0351f RK |
58 | \fB@#\fR). |
59 | It is intended to be used to mark the end of an expansion where that would | |
60 | otherwise be ambiguous. | |
3e1616b6 RK |
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 | |
daf0351f RK |
70 | in reversed order. |
71 | The input \fB@reverse{this}{that}\fR would therefore expand to "that this". | |
3e1616b6 | 72 | .SS "Sub-Expansions" |
daf0351f RK |
73 | Many expansions expand their argument with additional expansions defined. |
74 | For example, the \fB@playing\fR expansion expands its argument with the extra | |
3e1616b6 RK |
75 | expansion \fB@id\fR defined as the ID of the playing track. |
76 | .PP | |
daf0351f RK |
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. | |
3e1616b6 RK |
80 | .PP |
81 | In the case of a macro you can work around this by passing the value as an | |
daf0351f RK |
82 | argument. |
83 | Included files do not have arguments, so in this case you must rewrite the | |
84 | inclusion as a macro. | |
c6e44487 | 85 | .SS "Search Path" |
f2d306b4 | 86 | All template files are first searched for in \fIpkgconfdir\fR and then in |
c6e44487 | 87 | \fIpkgdatadir\fR. |
f2d306b4 RK |
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©\fR or \fB©\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. | |
3e1616b6 | 109 | .SH EXPANSIONS |
3e1616b6 RK |
110 | .\" Local Variables: |
111 | .\" mode:nroff | |
112 | .\" fill-column:79 | |
113 | .\" End: | |
114 |