| 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©\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. |
| 109 | .SH EXPANSIONS |
| 110 | .\" Local Variables: |
| 111 | .\" mode:nroff |
| 112 | .\" fill-column:79 |
| 113 | .\" End: |
| 114 | |