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