| Sign In | Sign Out | Subscribe to Mailing Lists | Unsubscribe or Change Settings | Help |
smoe.org mailing lists
Substitution variables and file templates
When Majordomo sends a reply message in response to a request, the document
that it sends is usually a template. The template may have one or more
keyword variables, for which Majordomo automatically substitutes the
appropriate value. Substitution variables are composed of a leading
dollar sign, followed by capital letters and underscores.
For example, when you use the command
help overview
Near the end of the document, it says
Majordomo 2, version $VERSION
However, what you see on your screen is
Majordomo 2, version 0.1200401130
Majordomo automatically substitutes the version number for the
VERSION keyword variable.
The most important use of variable substitutions is in the faq, info,
and intro files that are available through the commands with the same
names. Substitution variables are also used by some configuration
settings and by the announce and help commands.
Substitution variables are not the same as access rule variables. See
"help access_variables" for more information about access variables.
As an example of a variable, using this string in a file
$MJ
will cause the the address of the majordomo email interface to be
inserted before the user sees the file contents.
When you edit a document that contains substitution variables, be
certain to leave enough space for the text that will replace each
variable. Otherwise, some lines in the document may be longer than you
expected.
Variables that are not supported by a particular document or
configuration setting will remain unaltered. See "help error_files",
"help format_files" and "help reply_files" for a list of documents and
the substitutions that they support.
The $INCLUDE variable can be used to incorporate a separate document
into the current document. This variable must be followed by a dash and
the location of a file within the file space of your mailing list. For
example, the following substitution:
$INCLUDE-help/topics
will include the contents of the "help topics" document into the current
file. The line that contains the substitution must end immediately
after the file location.
Included files can also use the $INCLUDE substitution, but more
than 3 levels of nesting is taken to be an infinite loop, which will
cause an error message to be displayed.
The $INCLUDE substitution is supported by reply files, but not by error
files or format files.
If you misspell a variable, or use one that is not defined, it will
appear exactly as you typed it, including the dollar sign.
You can keep variable evaluation from happening by preceding the
dollar sign with a backslash, as in
\$MAJORDOMO
which will appear as simply "$MAJORDOMO" after the substitutions are
finished.
In addition, the text can be padded and justified, as illustrated
in this example:
$LIST:-18 X $COMMAND:11
The name of the mailing list is padded with spaces to at least 18 characters
and left-justified. The command is padded to at least 11 characters and
right-justified. If the mailing list name is "aardvark" and the command
is "subscribe" then this line would be displayed as
aardvark X subscribe
Padding in this manner is very useful for commands, such as who-enhanced,
that display a table of data with each column aligned properly.
See "help get" and "help put" for information on how to see, change,
or create the error, format, and reply files that use these substitutions.
Standard substitution variables
-------------------------------
There is a set of standard substitutions, that apply to most
of the Majordomo error, format, and reply files. Their names and values
(in the context of the GLOBAL list) are shown in the following list. Naturally,
some of the variables (LIST, OWNER, REQUEST, SUBLIST, and WHOAMI)
will vary depending upon the mailing list.
$ARCURL
(The URL that allows access to an external archive. This value is
determined by the archive_url configuration setting; see
"help configset_archive_url" for more information.)
$CONFIRM_URL http://www.smoe.org/cgi-bin/mj_confirm/domain=smoe.org?t=
(The location of the WWW interface to confirm a subscription,
posted message, or other Majordomo command.)
$DATE
The date at which a request was originally issued; in some cases
this may be the Date header from a posted message.
$DOMAIN smoe.org
(The name of the current domain, as determined at installation time)
$LIST GLOBAL
(The name of the current mailing list, or GLOBAL)
$MJ mj2@smoe.org
(The e-mail address of the majordomo server)
$MAJORDOMO mj2@smoe.org
(The e-mail address of the majordomo server)
$MJOWNER mj2-owner@smoe.org
(The e-mail address of the administrator of this domain)
$OWNER mj2-owner@smoe.org
(The e-mail address of the administrator of the current mailing list)
$PWLENGTH 4
(The minimum length of a new password. See "help password" and
"help admin_passwords" for details.)
$REQUEST mj2@smoe.org
(The "request" address for a mailing list)
$SITE smoe.org mailing lists
(A description of this domain, taken from the site_name configuration
setting.)
$SUBLIST
(An auxiliary list, if one is used. See "help auxiliary_list" for details.)
$UCLIST GLOBAL
(The name of the current mailing list, in capital letters)
$VERSION 0.1200401130
(Which version of Majordomo 2 is used at this site.)
$WHEREAMI smoe.org
(The name of the current domain.)
$WHOAMI mj2@smoe.org
(The list address, or the Majordomo server address in a GLOBAL context.)
$WWWADM_URL http://www.smoe.org/cgi-bin/mj_wwwadm/domain=smoe.org
(The location of the WWW interface for list administrators)
$WWWUSR_URL http://www.smoe.org/cgi-bin/mj_wwwusr/domain=smoe.org
(The location of the WWW interface for list subscribers)
Other variables
---------------
In time, a complete list of the other substitutions supported by
the error, format, and reply files will be presented here.
See "help error_files" for a description of each of the error files.
See "help format_files" for a description of each of the format files.
See "help reply_files" for a description of each of the reply files.
$ACKDENY_CHECKBOX
$ACKPOST_CHECKBOX
$ACKREJECT_CHECKBOX
$ACKSTALL_CHECKBOX
$ELIMINATECC_CHECKBOX
$HIDEADDRESS_CHECKBOX
$HIDEALL_CHECKBOX
$HIDEPOST_CHECKBOX
$POSTBLOCK_CHECKBOX
$PREFIX_CHECKBOX
$REPLYTO_CHECKBOX
$REWRITEFROM_CHECKBOX
$SELFCOPY_CHECKBOX
Check boxes for HTML forms used by the WWW interfaces to display a
personal setting for a particular subscription.
$ADDRESS
An e-mail address.
$ALIASES
The mail aliases required by your system's message transport
software for one or more mailing lists.
$ALL_FOOTERS
$ALL_FRONTERS
All of the list's message_footers and message_fronters, respectively (if
any), separated by blank lines.
$APPROVALS
The number of people who must use the accept command to approve
a stalled request.
$ARCHIVE
The archive name of a posted message, for example "200008".
This is not the same as the sequence number; see "help archive"
for more details.
$AUTHOR_NEXT
$AUTHOR_PREV
$DATE_NEXT
$DATE_PREV
$NUMERIC_NEXT
$NUMERIC_PREV
$SUBJECT_NEXT
$SUBJECT_PREV
$THREAD_NEXT
$THREAD_PREV
These substitutions contain the message numbers of the next and
previous messages within a mailing list archive, depending upon
the order in which the messages are sorted.
$BOUNCE_DATA
This substitution displays statistics and diagnotic messages for
addresses to which a posted message could not be delivered.
$BOUNCE_PERCENT
This variable contains the percentage of posted messages that have
bounced for a particular address.
$BOUNCES_DAY
$BOUNCES_MONTH
$BOUNCES_WEEK
These variables contain the number of delivery failures for a
particular address in the specified period of time.
$CAN_READ
This boolean variable is true if the person making a request has
permission to use the archive command for a particular mailing
list.
$CATEGORY
A configuration setting category.
$CGIDATA
A supplementary part of the URL of the current CGI script, for use
in the web interfaces when the URL is used in an anchor
("<a href=...>").
$CGIURL
The URL of the current CGI script, when one of the web interfaces
is being used.
$CHANGED
This substitution is used by the password command to indicate whether
or not the password was changed or merely reported. Its value is " "
if the password was changed, and '' otherwise.
$CHARSET
The character set of a message or part of a message.
$CHUNKSIZE
The number of addresses displayed at one time by the who command
in the wwwadm interface.
$CMDLINE
The command line that would be used to issue a command via e-mail
or the mj_shell program.
$CMDPASS
The password with which the current command was issued.
$COMMAND
The name of a Majordomo command.
$COMMENT
A description of a configuration setting or category.
$CONSECUTIVE
The number of consecutive messages to a particular address that have
bounced.
$CONSULT
" " if the type of a stalled command is "consult"; '' otherwise.
"consult" means that the moderators must confirm the command.
$CONTENT_TYPE
The content type of a message or part of a message.
$COUNT
The number of settings in a particular configuration category.
Also, the number of commands processed by the command parser.
Also, the number of attachments in a message processed by the
command parser.
$DESCRIPTION
A description of a mailing list, as determined by the description
and description_long configuration settings. Also, a description
of a digest, as determined by the digests configuration setting.
$DIAGNOSTIC
The explanation for a delivery failure that is extracted from a bounce
message.
$DIGESTNAME
The name of a digest, as determined by the digests configuration
setting.
$ELAPSED
The amount of time, in seconds, required for a command to execute.
$EXPIRE
The number of days before a request that has been stalled expires, or
in some cases the date at which it will expire. This value is
determined by the token_lifetime configuration setting
(see "help configset_token_lifetime" for details).
$EXTRA
The contents of the "extra" CGI parameter, which usually contains
arguments for a command.
$ERROR
An error message which describes why a command failed.
$FAIL
" " if a command invoked with the "accept" or "default user" command
failed; '' otherwise.
Also, a count of commands that failed.
$FINISH
The date of the latest of a group of messages or requests.
$FOOTER
$FRONTER
The list's message_footer and message_fronter, respectively. If there
are multiple fronters or footers, the first of each will be used.
$FULFILL
The date at which a delayed request will be completed
(see "help delay" for more information).
$HANDLER
When a bounce message is presented in a recognizable format, this
variable contains the name of the format (e.g., "DSN" or
"Compuserve").
$HOST
The host from which a posted message is distributed to the subscribers
of a mailing list. This value comes from the resend_host configuration
setting (see "help configset_resend_host" for more details).
$INACTIVE
" " if the "active" configuration setting of a newly created mailing
list is off; '' otherwise.
$ISPOST
" " if a token refers to a stalled posted message; '' if a token
refers to a Majordomo command.
$ISSUES
The number of issues of a digest that were delivered.
$LAST_RUN
$NEWEST_AGE
$NEXT_RUN
$OLDEST_AGE
The status of a particular digest: when it was last issued, when the
next issue might be delivered, and the ages of the oldest and newest
messages that are awaiting delivery.
$LINE
The line number at which a pattern matched part of the body of a
posted message.
$LINES
For the configshow command, this is the number of lines occupied
by a multi-line configuration setting value.
In the command parser, this is a number of unrecognized lines
that are skipped because the parser does not recognize them as
part of a command.
$LOCATION
In error messages for invalid e-mail addresses, this variable contains
the invalid portion of the address. In taboo match descriptions, this
variable contains the text that matched.
$MAX_AGE
$MAX_MSGS
$MAX_SIZE
$MIN_AGE
$MIN_MSGS
$MIN_SIZE
Constraints on digest delivery, as determined by the digests
configuration setting.
$MAXLENGTH
The size limit on a posted message, as determined by the maxlength
configuration setting.
$MESSAGE_ID
The message ID, from the "Message-Id" header, of a posted message.
$MODE
The command mode. For example, the command mode of the "who-enhanced"
command would be "enhanced."
$MSGNO
The archive name and number of a posted message, for example
"200008/12". This is not the same as the sequence number.
See "help archive" for more details.
$NEEDCOPY
The list of addresses that need to be replied to in order for everyone
who received a copy of the original messages to receive a copy of the
reply. This generally includes the list address plus the address of any
non-list-members whose addresses appear in the To: and CC: headers.
$NEWADDRESS
The e-mail address to which a command or posted message is forwarded.
$NEWCOMMAND
The Majordomo command that should be used instead of an obsolete
command (e.g., "configset" instead of the obsolete "newconfig").
$NEWLIST
The most recent name of a mailing list that has been created,
renamed, or destroyed with the createlist command.
$NOARCHIVE
" " if the archive for a new mailing list was not created
automatically; '' otherwise.
$NONMEMBER
" " if an address is not subscribed to the mailing list;
'' otherwise.
$NOTIFIED
" " if an acknowledgement message was sent to the victim of a
command; '' otherwise.
$OLDALIASES
The original aliases of a mailing list that has been renamed with
the createlist command.
$OLDLIST
The original name of a mailing list that has been renamed with
the createlist command.
$PART
The part number of one part of a posted message.
$PASSWORD
The personal password corresponding to a particular e-mail address,
or the master password of a newly created mailing list.
$PATTERN
A pattern listed in the taboo_headers configuration setting, or
another related setting.
$QSADDR
An e-mail address, altered to allow it to be included safely in the
query string of a URL.
$RANDOM_FOOTER
$RANDOM_FRONTER
A randomly chosen message_footer and message_fronter, respectively.
$REMIND
The number of days before a reminder for a request that requires
confirmation, is sent to the person whom the request affects.
This value is determined by the token_remind configuration setting
(see "help configset_token_remind" for details).
$REASONS
The reasons, supplied by the access rules, that a request was denied
or stalled (see "help configset_access_rules" for more details).
$REQUESTER
The e-mail address from which a Majordomo request was sent.
$SENDER
The e-mail address from which a posted message was sent, or the
envelope address used by a mailing list to deliver messages to the
subscribers.
$SEPARATOR
A line, in an e-mail message, that the command parser considers
a signature separator (see "help configset_signature_separator"
for more information).
$SEQNO
The sequence number of a message posted to a mailing list. This
value comes from the sequence_number configuration setting (see
"help configset_sequence_number" for more information).
$SESSIONUSER
The e-mail address of the person who initiated a majordomo session.
$SETTING
The name of a configuration setting category, in capital letters,
or the name of a configuration setting or default setting.
$SETTINGS
The names of the configuration settings within a particular
configuration category.
$STALL
" " if a command invoked with the "accept" or "default user" command
requires further approval; '' otherwise.
Also, a count of commands that stalled.
$START
The date of the earliest of a group of messages or requests.
$STATUS
The result of a request: succeed, stall, or fail.
A kind of bounce message: failure or warning.
$STRIPADDR
$STRIPUSER
A stripped address does not include any comments, such as the person's
full name.
$SUBJECT
The Subject header of a posted message.
$SUBLIST
The name of the auxiliary list to which a command applies (see
"help auxiliary_list" for more information).
$SUBSCRIBED
If a message was posted by a subscriber to the mailing list, this
value is empty. If not, it is the word "not".
$SUCCEED
" " if a command invoked with the "accept" or "default user" command
succeeded; '' otherwise.
Also, a count of commands that succeeded.
$TAG
The tag that is used to mark the end of a here document.
See "help here_document" for more details.
$TIME
The time of day at which a request was processed.
$TOKEN
The twelve-character identifier that is used to accept or reject
a stalled command (see "help tokeninfo" for more information.)
$TOPIC
When a help file is displayed, this value is replaced by the
name of the help file.
$TYPE
The type of a stalled command, such as "confirm" if the person
affected by the request must confirm the command, or "consult" if
the moderators must confirm the command.
In the context of taboo pattern matches, this is the type of
pattern that matched a header or body of a posted message, in
capital letters (e.g., "TABOO_BODY").
$URL
Identical to $CONFIRM_URL
$USER
The e-mail address from which a Majordomo request was originally sent.
(this needs to be reconciled with $REQUESTER)
$VALUE
The value of a default setting.
$VICTIM
The e-mail address of the person affected by a Majordomo command.
$WELCOME
" " if the owners' guide was mailed to the owners of a new mailing
list; '' otherwise.
$WILLACK
" " if an acknowledgement message will be mailed if a token is
accepted or rejected; '' otherwise.
Extensions for error and format files
-------------------------------------
Beyond the standard reply files, Majordomo comes with error and format
files that determine the output of the individual Majordomo commands.
Error files are used to display explanations when a command is
incorrect, not permitted, or otherwise unavailable. Format files
display the output of the individual commands, and vary depending
upon the interface. Currently, the e-mail and mj_shell interfaces
use the "text" format files, whereas the web interfaces use
the "wwwadm" and "wwwusr" format files.
There are three extensions to the substitutions which are used
by the error and format files.
1. A keyword variable prefixed with a question mark instead of a dollar
sign will cause the whole line to be omitted from the output
if the value is not set.
Example:
The archive is available on the web at ?ARCURL
2. A substitution value that is actually an array of values will
cause the same line to be displayed multiple times, once for
each value in the array. Other substitutions on the same line, which
only have one value, will be displayed only on the first line.
Example:
$LIST:-23 $DESCRIPTION
(This example is used by the lists command to display a list name and
a multiple-line description of the mailing list. Although the list name
only appears on the first line, a 23 space indentation appears on each
succeeding line, which keeps the lines of the description aligned with
one another.)
3. The special $HELP substitution, following by a colon and the name
of a help page (in upper-case letters), will cause a hypertext link
to that page to appear in the output of the WWW interfaces. In the text
formatting files, the variable is simply replaced by the name of the
page, in lower-case letters.
Example:
You may change your delivery class using the $HELP:SET command.
See Also:
help access_variables
help admin_documents
help announce
help configset_access_rules (for mailfile and deny usage)
help configset_site_name
help configset_welcome_files (for additional files that can be sent)
help digest (for additional file names and usage)
help error_files
help format_files
help get (obtain existing files)
help help
help here_document
help put (create or update files by email)
help reply_files
This is the "variables" help document for
Majordomo 2, version 0.1200401130.
For a list of all help documents, send the following command:
help topics
in the body of a message to mj2@smoe.org.
For assistance, please contact the smoe.org administrators.
| Sign In | Sign Out | Subscribe to Mailing Lists | Unsubscribe or Change Settings | Help |