summaryrefslogtreecommitdiffabout
path: root/doc
Side-by-side diff
Diffstat (limited to 'doc') (more/less context) (ignore whitespace changes)
-rw-r--r--doc/wydawca.texi156
1 files changed, 84 insertions, 72 deletions
diff --git a/doc/wydawca.texi b/doc/wydawca.texi
index 2763b6d..8950987 100644
--- a/doc/wydawca.texi
+++ b/doc/wydawca.texi
@@ -728,52 +728,68 @@ example above:
@end group
@end smallexample
-@anchor{meta-interpretation}
-@cindex meta-interpretation
-@cindex meta-variables
-Depending on the context, the contents of a quoted string may be
-subject to @dfn{meta-variable interpretation}. During this process,
-any sequence
+@anchor{variable expansion}
+@cindex variable expansion
+@cindex variables
+Depending on the context, the quoted string may be subject to
+@dfn{variable expansion}.
-@smallexample
-$@{@var{var}@}
-@end smallexample
+During variable expansion, references to variables
+in the string are replaced with their actual values. A variable
+reference has two basic forms:
-@noindent
-where @var{var} is the name of a defined meta-variable, is replaced with
-the value of the variable. This sequence is called @dfn{meta-
-reference}. For example, if the meta-variable @samp{user} has the
-value @samp{smith}, then the string
-
-@smallexample
-"where user = '$@{user@}'"
-@end smallexample
+@example
+ $@var{v}
+ $@{@var{v}@}
+@end example
@noindent
-becomes
+where @var{v} is the variable name. The notation in curly braces
+serves several purposes. First, it should be used if the variable
+reference is immediately followed by an alphanumeric symbol, which
+will otherwise be considered part of it (as in @samp{$@{home@}dir}).
+Secondly, this form allows for specifying the action to take if the
+variable is undefined or expands to an empty value.
-@smallexample
-"where user = 'smith'"
-@end smallexample
-
-If the name of the variable consists of a single character, the curly
-braces around it may be omitted. Thus, @code{$@{u@}} and @code{$u} are
-equivalent.
+The following special forms are recognized:
-If @var{var} is not defined, the meta-reference is left unchanged.
+@table @asis
+@item $@{@var{variable}:-@var{word}@}
+@dfn{Use Default Values}. If @var{variable} is unset or null, the expansion
+of @var{word} is substituted. Otherwise, the value of @var{variable} is
+substituted.
+
+@item $@{@var{variable}:=@var{word}@}
+@dfn{Assign Default Values}. If @var{variable} is unset or null, the
+expansion of @var{word} is assigned to variable. The value of
+@var{variable} is then substituted.
+
+The assigned value remains in effet during expansion of the current string.
+
+@item $@{@var{variable}:?@var{word}@}
+@dfn{Display Error if Null or Unset}. If @var{variable} is null or unset,
+the expansion of @var{word} (or a message to that effect if @var{word} is
+not present) is output to the current logging channel. Otherwise, the
+value of @var{variable} is substituted.
+
+@item $@{@var{variable}:+@var{word}@}
+@dfn{Use Alternate Value}. If @var{variable} is null or unset, nothing is
+substituted, otherwise the expansion of @var{word} is substituted.
+@end table
-The special sequence @samp{$-} causes removal of it and any character
-following it. Most often it is used as a next-to-last character
-on a line, right before the newline. In this position it causes the
-removal of the trailing newline, similar to @samp{dnl} in @command{m4}.
-@xref{listings, Triplet Listings}, for a detailed description and
-examples of @samp{$-} use.
+These constructs test for a variable that is unset or null. Omitting
+the colon results in a test only for a variable that is unset.
-To insert a literal @samp{$} character in a string that is subject to
-meta-variable interpretation, duplicate it: @samp{$$}.
+@anchor{handling of undefined variables}
+@cindex expansion of undefined variables
+@cindex undefined variable, expansion
+If a string contains a reference to an undefined variable,
+@command{wydawca} will report an error and abort. To
+gracefully handle such cases, use the @dfn{default value construct},
+defined above.
-The exact set of defined meta-variables and their values depend on the
-context and are discussed in detail below.
+@FIXME{Implement the expand-undefined setting, similar to the one in
+rush}.
@anchor{here-document}
@item Here-document
@@ -1496,41 +1512,42 @@ See below for a detailed description of these dictionary types.
@anchor{query}
@deffn {Config: dictionary} query string
Sets the query used for retrieving the data. The @var{string} is
-subject to meta-variable interpretation (@pxref{meta-interpretation}). The
-following meta-variables are defined:
+subject to variable expansion (@pxref{variable expansion}). The
+following variables are defined in this context:
@table @code
-@kwindex p
@kwindex project
-@item p
-@itemx project
+@item project
The system name of the project for which the triplet is
submitted. It is defined as the value of directive
@code{directory}, or, in case this value contains slashes, the
shortest initial prefix of that value, not containing slashes.
+@kwindex spool
@item spool
The name of the distribution spool where this upload originates
(@pxref{spool}).
+@kwindex url
@item url
The @acronym{URL} of the spool, as set in the @code{url} statement
of the @code{spool} block (@pxref{spool, url}).
+@kwindex dir
@item dir
Directory (relative to the project distribution root) where the
files are going to be uploaded.
-@item dest-dir
+@kwindex dest_dir
+@item dest_dir
Spool destination directory (@pxref{spool, destination}).
-@item source-dir
+@kwindex source_dir
+@item source_dir
Spool source directory (@pxref{spool, source}).
-@kwindex u
@kwindex user
-@item u
-@itemx user
+@item user
@itemx user:name
The system name of the user that submitted the triplet. This is
defined only for @samp{project-owner} dictionaries.
@@ -2010,8 +2027,9 @@ spool @var{tag} @{
@end smallexample
The @var{tag} argument defines a unique identifier for this spool. It
-will be used in log messages, timers (@pxref{spool-timers}) and in
-meta-variable interpretation (@pxref{meta-interpretation}).
+will be used in log messages, timers (@pxref{spool-timers}) and is
+available for variable expansion (@pxref{variable expansion}) as the
+@samp{$spool} variable.
@end deffn
@deffn {Config: spool} alias list
@@ -2028,7 +2046,7 @@ description of this feature.
@deffn {Config: spool} url string
Defines download @acronym{URL}, associated with this spool. Its value
-may be used as @samp{$@{url@}} meta-variable in mail notifications.
+may be used as the variable @samp{$url} in mail notifications.
@end deffn
@deffn {Config: spool} source dir
@@ -2215,11 +2233,11 @@ notification}) is generated.
In case of non-zero return, the script may return additional
diagnostics on the standard output. This diagnostics will be
-available for use in notification messages via the @samp{check:diagn}
-meta-variable.
+available for use in notification messages via the @samp{$check:diagn}
+variable.
Additionally, the actual return code of the script, in decimal, is
-available in the @samp{check:result} meta-variable. If the script
+available in the @samp{$check:result} variable. If the script
terminates on a signal, the value of this variable is
@samp{SIG+@var{n}}, where @var{n} is the signal number.
@end deffn
@@ -2776,7 +2794,7 @@ mailer "|/bin/nullmail localhost -F$@{sender@} $@{rcpt@}"
@cindex notification message template
@cindex message template
Each notification message is build from a message template, by
-expanding meta-variables (@pxref{meta-interpretation}) within it.
+expanding variables (@pxref{variable expansion}) within it.
The message text may be specified either in place within the
configuration directive it belongs to (@pxref{notification}), or
defined by @code{define-message} statement.
@@ -2874,8 +2892,8 @@ the @acronym{GPG} home directory (@pxref{gpg-homedir}).
The statistics message is sent to addresses configured by
@code{admin-address} statement (@pxref{mod_mailutils, admin-address}).
-@cindex meta-variables in admin notifications
-The meta-variables available for use in statistics reports are:
+@cindex variables in admin notifications
+The variables available for use in statistics reports are:
@anchor{statistics variables}
@multitable @columnfractions 0.30 0.70
@@ -2912,7 +2930,7 @@ triplets.
@kwindex stat:rmsymlinks
@item stat:rmsymlinks @tab Number of symbolic links removed.
@kwindex stat:check-failures
-@item stat:check-failures @tab Number of verification failures
+@item stat:check_failures @tab Number of verification failures
(@pxref{verification}).
@end multitable
@@ -3060,9 +3078,9 @@ template, or a reference to a template previously defined by a
@kwindex dir
@item dir @tab Directory (relative to the project distribution
root) where the files where uploaded.
-@kwindex dest-dir
+@kwindex dest_dir
@item dest-dir @tab Value of the @code{destination} keyword.
-@kwindex source-dir
+@kwindex source_dir
@item source-dir @tab Value of the @code{source} keyword.
@kwindex triplet:dist
@item triplet:dist @tab File name of the main distribution file.
@@ -3082,7 +3100,7 @@ $@{triplet:ls:dir@}
@end smallexample
}.
@kwindex triplet:ls:upload
-@item triplet:upload @tab Listing of the uploaded files (see below).
+@item triplet:ls:upload @tab Listing of the uploaded files (see below).
@kwindex triplet:dist
@item triplet:ls:dist @tab Listing of the main distribution file (see below).
@kwindex triplet:ls:sig
@@ -3093,7 +3111,7 @@ $@{triplet:ls:dir@}
@item user @tab System name of the user who uploaded the triplet.
@kwindex user:name
@item user:name @tab System name of the user who uploaded the triplet.
-@kwindex user:real-name
+@kwindex user:real_name
@item user:real-name @tab Real name of the user who uploaded the triplet.
@kwindex user:email
@item user:email @tab Email of the user who uploaded the triplet.
@@ -3164,14 +3182,8 @@ example, here is a possible @code{$@{triplet:ls:full@}} listing:
-rw-r--r-- gray user 62 2007-09-06 22:14:35 tar-1.18.tar.gz.directive.asc
@end smallexample
- The following example shows how to configure success notification
-for the user. Notice the use of the @samp{$-} after
-@samp{$@{triplet:ls:upload@}}: it removes the newline character after
-it and thus allows for more natural indentation of the next
-line. Without it, the expanded message would have contained two
-newlines after the full listing: one produced by
-@samp{$@{triplet:ls:upload@}} and the second one taken verbatim from
-the message template.
+ The example in the following subsection shows how to configure
+success notification for the user.
@node mod_mailutils example
@subsubsection Example of mod_mailutils configuration
@@ -3208,7 +3220,7 @@ module-init mailutils @{
files archived ..................... $@{stat:archives@}
symlinks created ................... $@{stat:symlinks@}
symlinks removed ................... $@{stat:rmsymlinks@}
- verification failures .............. $@{stat:check-failures@}
+ verification failures .............. $@{stat:check_failures@}
Timings:
@@ -3247,7 +3259,7 @@ notify-event @{
Upload of $@{project@} to $@{url@}/$@{dir@} finished successfully.
Files uploaded:
- $@{triplet:ls:upload@}$-
+ $@{triplet:ls:upload@}
Resource usage: $@{timer:triplet:real@}/$@{timer:wydawca:real@}r \
$@{timer:triplet:user@}/$@{timer:wydawca:user@}u \
@@ -3324,7 +3336,7 @@ files uploaded: $@{stat:uploads@}
files archived: $@{stat:archives@}
symlinks created: $@{stat:symlinks@}
symlinks removed: $@{stat:rmsymlinks@}
-check failures: $@{stat:check-failures@}
+check failures: $@{stat:check_failures@}
EOT;
@end group
@end example

Return to:

Send suggestions and report system problems to the System administrator.