/ 
App-tpnotify-1.04
River stage zero No dependents
/ App::tpnotify

NAME

tpnotify - Notifies translationproject.org about new POT file

SYNOPSIS

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]

DESCRIPTION

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:

mbox:[//]PATHNAME

UNIX mailbox located at PATHNAME (relative or absolute).

mh:[//]PATHNAME

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:[//]PATHNAME

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.

CONFIGURATION

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:

keep=1 | 0

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.

template-file=FILE

Name of the file to read template from. See also the --template command line option.

template=TEXT

Template for the message. The TEXT is normally a here-document. See the TEMPLATE section for a description of its format.

signature-file=FILE

Read signature from the given file. See also the --signature command line option.

mailer=SPEC

Sets mailer. The argument is a mailer specification as discussed in the description of the --mailer command line option below.

sender=EMAIL

Sets the sender email address. See also the --sender option.

fullname=STRING

Sets the real name of the recipient. See the --fullname command line option.

domain=DOMAIN

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.

to=EMAIL

Sets the recipient address to be used instead of the emails from To:, Cc:, and Bcc: headers of the constructed message.

add=HDR:VAL

Adds the given header to the message. See also the --add command line option.

refile-method=perl | mailutils

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

TEMPLATE

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

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.

$fullname

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.

$localdomain

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.

$signature

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.

$archive_url

URL of the tarball as supplied in the command line.

$archive_file

Name of the tarball. It is the last pathname component from URL.

$topdir

Project top level directory as seen in the downloaded tarball.

$package_name

Full package name. E.g. GNU dico.

$package_tarname

Package tarname. It is the $package_name value with the eventual GNU prefix stripped off.

$package_version

Package version number.

$package_base

Package base name, constructed as a concatenation of values of the $package_tarname and $package_version, separated by a dash.

$release_type

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.

OPTIONS

--force

Force submitting the message even if the downloaded POT file does not pass checks.

--no-config

Don't read configuration file.

--no-signature

Don't read signature file. The $signature template variable will be undefined.

--to=EMAIL

Send message to EMAIL, instead of the addresses specified in the message itself.

-A, --alpha

Assume URL is an alpha release.

-D, --domain=DOMAIN

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).

-F, --fullname=NAME

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.

-S, --stable

Assume URL is a stable release.

-a, --add=HDR:VAL

Append the given header to the message.

-c, --config=FILE

Read configuration from FILE, instead of ~/.tpnotify.

-d, --debug

Debug the mail sending transaction.

-f, --from=EMAIL

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).

-k, --keep

If an error occurs, don't remove the temporary directory. This allows the user to get more insight into the reasons of the failure.

-m, --mailer=SPEC

Sets the mailer. The SPEC is one of the following:

sendmail:

Use the default sendmail binary for sending.

sendmail:program

Use the sendmail-compatible program. program is the absolute pathname of the program.

smtp://[USER[:PASS]@]HOSTNAME[:PORT]

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.

-n, --dry-run

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.

--refile-method=perl | mailutils

Select the method to implement Fcc. Refer to the description of the refile-method setting in the CONFIGURATION chapter for a detailed discussion.

-s, --signature=FILE

Read signature from FILE. The content of the file is available as the value of the $signature template variable.

-t, --template=FILE

Read template from FILE. See the section TEMPLATE for its format.

-v, --verbose

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.

-h

Produce a short help summary.

--help

Print a detailed manual.

--usage

Display a short command line usage summary.

EXIT CODE

0

Success

64

Command line usage error.

65

Downloaded archive contains invalid data. See the error messages for details.

66

Required input file cannot be opened.

69

Subprocess exited with error status or on signal.

71

Failed to run subprocess, or failed to change the directory.

73

Required output file cannot be created or written.

78

Configuration error.

BUGS

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.

AUTHOR

Sergey Poznyakoff <gray@gnu.org>

LICENSE

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.