tpnotify - Notifies translationproject.org about new POT file
tpnotify [-ANSdnkv] [-D DOMAIN] [-F NAME] [-a HDR:VALUE [-c FILE] [-f FROM] [-m SPEC] [-s FILE] [-t FILE] [--add=HDR:VAL] [--alpha] [--config=FILE] [--debug] [--domain=DOMAIN] [--dry-run] [--force] [--from=EMAIL] [--fullname=NAME] [--keep] [--mailer=SPEC] [--no-config] [--no-signature] [--refile-method=perl | mailutils] [--signature=FILE] [--stable] [--template=FILE] [--to=EMAIL] [--verbose] URL
tpnotify [-h] [--help] [--usage]
Notifies the coordinator of the Translation Project about new POT file available at URL. The URL must point to a tarball of a package registered at TP (http://translationproject.org/domain/). The tool works as follows:
First of all, the indicated URL is downloaded to a temporary location on disk. The contents of the retrieved tarball is inspected. It must contain the file configure.ac in the project top level directory and one or more files with the .pot suffix in the po subdirectory.
These files are extracted. The configure.ac is parsed in order to determine the package name and version (from the AC_INIT statement). The canonical package name is formed by concatenating the package name (with the eventual GNU prefix stripped), a dash, and the version number. The name of the POT file is constructed by appending the .pot suffix to the base name, This file is looked up in the po subdirectory.
When this initial stage is through, the message template is expanded. See the TEMPLATE section below, for a detailed discussion of this stage. The resulting email message is then sent. Unless the --to option is given, the recipients are obtained from the headers To:, Cc:, and Bcc: of the formatted message. The --to option supplies the recipient email to be used instead of those.
The Fcc: header can be used to save the copy of the message being sent in a mailbox. If its value is an absolute or relative pathname, it is assumed to be a mailbox in traditional UNIX format (relative pathnames are expanded relative to the user home directory). Otherwise, it is a folder url:
UNIX mailbox located at PATHNAME (relative or absolute).
MH mailbox at PATHNAME. Relative pathnames are resolved by prepending the value of the Path header from the ~/.mh_profile file. If not defined, the ~/Mail directory is assumed.
Maildir folder at PATHNAME. Relative pathnames are relative to the current user's home directory.
Two methods can be used to support Fcc refiling: the perl method, which uses the Mail::Box::Manager Perl package, and the mailutils method, which uses GNU mailutils. By default, tpnotify attempts to use perl, and falls back to mailutils if that's not possible. If the latter is not available as well, it issues an error message and terminates. The user can select the refiling method using the --refile-method option. See the BUGS section for details.
Additional configuration is supplied in configuration file and command line. The latter overrides the former. See the section CONFIGURATION for a detailed discussion of the configuration file format.
The -v (--verbose) command line option instructs the tool to verbosely list each step being executed. Additionally, the -d (--debug) option enables a detailed printout of debugging information describing the mail sending process.
The -n (--dry-run) option causes the program to verbosely print what is being done (as if given the --verbose option), but not actually send the constructed message.
The default configuration file is named .tpnotify and is located in the current user home directory. It's OK if it does not exist. In this case the tool will use the built-in defaults. Two command line options are provided to alter that behavior. The -c FILE (--config=FILE) option causes the program to read configuration file from FILE. It is an error if that file does not exist or is unreadable. The --no-config option instructs tpnotify to ignore the configuration file.
When reading the configuration file, empty lines and lines starting with a hash sign (#) are ignored. Remaining lines must contain valid configuration statements,
A statement consists of a keyword, followed by an equals sign and a value. Arbitrary amount of white space are allowed at the beginning and end of line, as well as around the equals sign. Multiline values can be entered using the familiar here-document syntax. A here-document is introduced by the << marker followed by arbitrary word. The lines following that construct are collected and concatenated until a line is found that contains only that word alone. The word must appear at the beginning of the line (no leading whitespace allowed). However, whitespace is allowed between the word and end of line. For example
template = <<EOF To: <coordinator@translationproject.org> Subject: $package_base.pot $archive_url EOF
The valid statements are as follows:
If an error occurs, don't remove the temporary directory. This allows the user to get more insight into the reasons of the failure.
See also the --keep option.
Name of the file to read template from. See also the --template command line option.
Template for the message. The TEXT is normally a here-document. See the TEMPLATE section for a description of its format.
Read signature from the given file. See also the --signature command line option.
Sets mailer. The argument is a mailer specification as discussed in the description of the --mailer command line option below.
Sets the sender email address. See also the --sender option.
Sets the real name of the recipient. See the --fullname command line option.
Sets the sender domain name. This is used when creating the sender email address to be used in the From: header. See also the --domain command line option.
Sets the recipient address to be used instead of the emails from To:, Cc:, and Bcc: headers of the constructed message.
Adds the given header to the message. See also the --add command line option.
Selects the method to implement Fcc. The value perl means to use Mail::Box::Manager perl package (https://metacpan.org/release/Mail-Box). The value mailutils means to use the movemail program from GNU mailutils (https://mailutils.org).
By default, the first available method is used. See the BUGS section for possible reasons to use this setting.
An example of the configuration file follows:
# Example configuration file for tpnotify # mailer = smtp://127.0.0.1:24 from = gray@gnu.org template = <<EOT To: <coordinator@translationproject.org> Subject: $package_base.pot The new $release_type version of $package_name is available at: $archive_url $signature EOT
The template is an email message conforming to the RFC-2822. It can (and, actually must) contain variables that will be replaced with their actual values during the expansion. The variables are:
Sender email address. It is constructed by concatenating the login name of the invoking user, the @ sign, and the local host name. If the --domain command line option, or domain configuration statement is used, its value is substituted instead of the local host name. If the --from option or sender configuration statement is used, its value overrides the constructed one.
Full real name of the sender. It can be supplied by the --fullname command line option or fullname configuration statement. If neither of these is present, the name is obtained from the Gecos line in the passwd entry of the invoking user.
Local domain name. It is the value of the command line option --domain. If not present, the value of the configuration statement domain is used. If that is not present either, then the local host name is used instead.
Contents of the signature file with the final newline character removed. The file location is given by the command line option --signature or the configuration statement --signature-file.
URL of the tarball as supplied in the command line.
Name of the tarball. It is the last pathname component from URL.
Project top level directory as seen in the downloaded tarball.
Full package name. E.g. GNU dico.
Package tarname. It is the $package_name value with the eventual GNU prefix stripped off.
Package version number.
Package base name, constructed as a concatenation of values of the $package_tarname and $package_version, separated by a dash.
Package type: alpha, or stable. Unless supplied with the corresponding command line option, it is determined by analyzing $package_number. The type is alpha, if the number contains three numeric parts, separated by dots, and the value of the last part is greater than or equal to 90. Otherwise, the type is stable.
Force submitting the message even if the downloaded POT file does not pass checks.
Don't read configuration file.
Don't read signature file. The $signature template variable will be undefined.
Send message to EMAIL, instead of the addresses specified in the message itself.
Assume URL is an alpha release.
Use DOMAIN as the sender domain. This is used when creating the sender email address to be used in the From: header. It is constructed by concatenating the login name of the invoking user, the @ sign, and the local host name (or DOMAIN, if set).
Set the full real name of the sender. It is used to construct the From: header. When using sendmail mailer, it will also be passed with the -F option to sendmail.
Assume URL is a stable release.
Append the given header to the message.
Read configuration from FILE, instead of ~/.tpnotify.
Debug the mail sending transaction.
Sets the sender email address. Unless this option is supplied, the email address of the sender of the message will be constructed by concatenating the login name of the invoking user, the @ sign, and the local host name (or the local domain, if set via the --domain option).
Sets the mailer. The SPEC is one of the following:
Use the default sendmail binary for sending.
Use the sendmail-compatible program. program is the absolute pathname of the program.
Send mail using SMTP. HOSTNAME is the hostname or IP address of the mail relay to use. PORT, if supplied, is the port number to use instead of the default 25. Optional USER and PASS provide credentials, if the relay requires authentication.
Don't actually send the message. Verbosely print what is being done (see the --verbose option) and display the content of the message that would have been sent.
Select the method to implement Fcc. Refer to the description of the refile-method setting in the CONFIGURATION chapter for a detailed discussion.
Read signature from FILE. The content of the file is available as the value of the $signature template variable.
Read template from FILE. See the section TEMPLATE for its format.
Verbosely print what is being done.
The following options are informative. They cause the program to print the required piece of information and exit. The remaining options and arguments are silently ignored.
Produce a short help summary.
Print a detailed manual.
Display a short command line usage summary.
Success
Command line usage error.
Downloaded archive contains invalid data. See the error messages for details.
Required input file cannot be opened.
Subprocess exited with error status or on signal.
Failed to run subprocess, or failed to change the directory.
Required output file cannot be created or written.
Configuration error.
If your template file contains an Fcc header pointing to a MH folder, you will get the following message:
WARNING: Folder already locked with file <FILENAME>
This is not a tpnotify bug, but a bug of Mail::Box::Manager. It has been reported (see https://rt.cpan.org/Public/Bug/Display.html?id=130193) and hopefully it will be fixed in one of the future versions of Mail::Box::Manager.
This is only a warning and can safely be ignored. If it does bother you, you can switch to GNU mailutils for refiling the message. To do so, first install movemail from GNU mailutils (the exact instructions vary depending on the distro you are using), and then use the --refile-method=mailutils option or refile-method=mailutils statement in your ~/.tpnotify configuration file.
Sergey Poznyakoff <gray@gnu.org>
GPLv3+: GNU GPL version 3 or later, see http://gnu.org/licenses/gpl.html
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.
To install App::tpnotify, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::tpnotify
CPAN shell
perl -MCPAN -e shell install App::tpnotify
For more information on module installation, please visit the detailed CPAN module installation guide.