| 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 |
| 30 | letter or digit). |
| 31 | No spacing is allowed between the "@" and the expansion name. |
| 32 | .PP |
| 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. |
| 36 | .PP |
| 37 | Arguments may be separated from one another and the expansion name by |
| 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). |
| 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 |
| 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. |
| 57 | .TP |
| 58 | .B @_ |
| 59 | This expands to nothing (but does not have the line-eating behaviour of |
| 60 | \fB@#\fR). |
| 61 | It is intended to be used to mark the end of an expansion where that would |
| 62 | otherwise be ambiguous. |
| 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 |
| 72 | in reversed order. |
| 73 | The input \fB@reverse{this}{that}\fR would therefore expand to "that this". |
| 74 | .SS "Sub-Expansions" |
| 75 | Many expansions expand their argument with additional expansions defined. |
| 76 | For example, the \fB@playing\fR expansion expands its argument with the extra |
| 77 | expansion \fB@id\fR defined as the ID of the playing track. |
| 78 | .PP |
| 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. |
| 82 | .PP |
| 83 | In the case of a macro you can work around this by passing the value as an |
| 84 | argument. |
| 85 | Included files do not have arguments, so in this case you must rewrite the |
| 86 | inclusion as a macro. |
| 87 | .SS "Search Path" |
| 88 | All template files are first searched for in \fIpkgconfdir\fR and then in |
| 89 | \fIpkgdatadir\fR. |
| 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. |
| 111 | .SH EXPANSIONS |
| 112 | .\" Local Variables: |
| 113 | .\" mode:nroff |
| 114 | .\" fill-column:79 |
| 115 | .\" End: |
| 116 | |