X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/blobdiff_plain/3e1616b61e001867875f42e3f09edb1c53db8096..c41b2cac164b413128cc26384f1644de795008f8:/doc/disorder_templates.5.head diff --git a/doc/disorder_templates.5.head b/doc/disorder_templates.5.head index dd4f751..fe100f7 100644 --- a/doc/disorder_templates.5.head +++ b/doc/disorder_templates.5.head @@ -1,20 +1,18 @@ .\" .\" Copyright (C) 2008 Richard Kettlewell .\" -.\" This program is free software; you can redistribute it and/or modify +.\" This program is free software: you can redistribute it and/or modify .\" it under the terms of the GNU General Public License as published by -.\" the Free Software Foundation; either version 2 of the License, or +.\" the Free Software Foundation, either version 3 of the License, or .\" (at your option) any later version. -.\" -.\" This program is distributed in the hope that it will be useful, but -.\" WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -.\" General Public License for more details. -.\" +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" .\" You should have received a copy of the GNU General Public License -.\" along with this program; if not, write to the Free Software -.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 -.\" USA +.\" along with this program. If not, see . .\" .TH disorder_templates 5 .SH NAME @@ -27,18 +25,19 @@ An expansion starts with an at ("@") symbol and takes the form of an expansion name followed by zero or more arguments. .PP Expansion names may contain letters, digits or "-" (and must start with a -letter or digit). No spacing is allowed between the "@" and the expansion -name. +letter or digit). +No spacing is allowed between the "@" and the expansion name. .PP -Each argument is bracketed. Any of "(" and ")", "[" and "]" or "{" and "}" may -be used but all arguments for a given expansion must use the same bracket pair. +Each argument is bracketed +Any of "(" and ")", "[" and "]" or "{" and "}" may be used but all arguments +for a given expansion must use the same bracket pair. .PP Arguments may be separated from one another and the expansion name by -whitespace (including newlines and even completely blank lines). The parser -always reads as many arguments as are available, even if that is more than the -expansion name can accept (so if an expansion is to be followed by an open -bracket of the same kind it uses, you must use the \fB@_\fR separator; see -below). +whitespace (including newlines and even completely blank lines). +The parser always reads as many arguments as are available, even if that is +more than the expansion name can accept (so if an expansion is to be followed +by an open bracket of the same kind it uses, you must use the \fB@_\fR +separator; see below). .PP Arguments are expanded within themselves following the same rules, with a few exceptions discussed below. @@ -50,13 +49,15 @@ This expands to a single "@" sign. .TP .B @# This expands to nothing, and moreover removes the rest of the line it appears -on and its trailing newline. It is intended to be used as a comment market but -can also be used to eliminate newlines introduced merely to keep lines short. +on and its trailing newline. +It is intended to be used as a comment market but can also be used to eliminate +newlines introduced merely to keep lines short. .TP .B @_ This expands to nothing (but does not have the line-eating behaviour of -\fB@#\fR). It is intended to be used to mark the end of an expansion where -that would otherwise be ambiguous. +\fB@#\fR). +It is intended to be used to mark the end of an expansion where that would +otherwise be ambiguous. .SS "Macros" It is possible to define new expansions using the \fB@define\fR expansion. For example, @@ -66,25 +67,46 @@ example, .fi .PP defines an expansion called \fB@reverse\fR which expands to its two arguments -in reversed order. The input \fB@reverse{this}{that}\fR would therefore expand -to "that this". +in reversed order. +The input \fB@reverse{this}{that}\fR would therefore expand to "that this". .SS "Sub-Expansions" -Many expansions expand their argument with additional expansions defined. For -example, the \fB@playing\fR expansion expands its argument with the extra +Many expansions expand their argument with additional expansions defined. +For example, the \fB@playing\fR expansion expands its argument with the extra expansion \fB@id\fR defined as the ID of the playing track. .PP -The scope of these sub-expansions is purely lexical. Therefore if you invoke a -macro or include another template file, if the sub-expansions appear within it -they will not be expanded. +The scope of these sub-expansions is purely lexical. +Therefore if you invoke a macro or include another template file, if the +sub-expansions appear within it they will not be expanded. .PP In the case of a macro you can work around this by passing the value as an -argument. Included files do not have arguments, so in this case you must -rewrite the inclusion as a macro. -.SS macros.tmpl -Before any page is expanded, the CGI will process \fBmacros.tmpl\fR (and -discard any output). This defines a collection of commonly used macros. +argument. +Included files do not have arguments, so in this case you must rewrite the +inclusion as a macro. +.SS "Search Path" +All template files are first searched for in \fIpkgconfdir\fR and then in +\fIpkgdatadir\fR. +.SS "macros.tmpl and user.tmpl" +Before any template is expanded, the CGI will process \fBmacros.tmpl\fR and +discard any output. +This defines a collection of commonly used macros. +.PP +Following this the CGI will process \fBuser.tmpl\fR, again discarding output. +This can be used to override the common macros without editing the installed +version of \fBmacros.tmpl\fR, or to define new ones. +.PP +It is not an error if \fBuser.tmpl\fR does not exist. +.SS "Character Encoding" +The CGI does not (currently) declare any character encoding. +This could be changed quite easily but in practice is not a pressing necessity. +.PP +The recommended approach is to treat the templates as ASCII files and if +non-ASCII characters are required, use HTML entities to represent them. +.PP +For example, to represent the copyright sign, use \fB©\fR or \fB©\fR. +.PP +If you know the decimal or hex unicode value for a character then you can use +\fB&#NNN;\fR or \fB&#xHHHH;\fR respectively. .SH EXPANSIONS -This section lists the supported expansions. .\" Local Variables: .\" mode:nroff .\" fill-column:79