From: Richard Kettlewell Date: Sat, 17 May 2008 16:32:55 +0000 (+0100) Subject: various cleanups and docs improvements X-Git-Tag: 4.0~76^2~16 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/daf0351f962a969c28bea01ed6b66453cccfe556 various cleanups and docs improvements --- diff --git a/doc/disorder_templates.5.head b/doc/disorder_templates.5.head index dd4f751..f876f80 100644 --- a/doc/disorder_templates.5.head +++ b/doc/disorder_templates.5.head @@ -27,18 +27,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 +51,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,23 +69,25 @@ 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. +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. +discard any output). +This defines a collection of commonly used macros. .SH EXPANSIONS This section lists the supported expansions. .\" Local Variables: diff --git a/doc/disorder_templates.5.tail b/doc/disorder_templates.5.tail index 996a205..a73ec89 100644 --- a/doc/disorder_templates.5.tail +++ b/doc/disorder_templates.5.tail @@ -16,6 +16,18 @@ .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 .\" USA .\" +.SH "NOTES" +.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 "SEE ALSO" .BR disorder_config (5) .\" Local Variables: diff --git a/server/macros-disorder.c b/server/macros-disorder.c index f2d9cac..cec504c 100644 --- a/server/macros-disorder.c +++ b/server/macros-disorder.c @@ -158,11 +158,6 @@ static int exp_part(int nargs, else return 0; } - fprintf(stderr, "track=[%s] part=[%s] context=[%s] dcgi_client=[%p]\n", - track, - part, - !strcmp(context, "short") ? "display" : context, - dcgi_client); if(dcgi_client && !disorder_part(dcgi_client, &s, track, diff --git a/templates/help.tmpl b/templates/help.tmpl index 6011c6e..44d75b2 100644 --- a/templates/help.tmpl +++ b/templates/help.tmpl @@ -47,8 +47,8 @@ USA being listed first.) Where possible, estimated start times are given.

-

Each track has a @label{playing.scratch} +

Each track has a @label{playing.remove} button next to it. For the currently playing track this can be used to stop playing the track before it has finished; this is called “scratching”. For a track in the queue it diff --git a/templates/options.labels b/templates/options.labels index 86586aa..eabcb4f 100644 --- a/templates/options.labels +++ b/templates/options.labels @@ -236,7 +236,7 @@ label heading.album Album label heading.title Title label heading.length Length -# Role images. See the documentation for @images:NAME@. +# Role images. See the documentation for @image{NAME}. label images.enabled tick.png label images.disabled cross.png label images.remove cross.png