| | 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 | |
~mdw / disorder / blame_incremental