.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH FOTOWIRE.PL 1 "December 2003" "fotowire.pl" "Version 0.1"

.SH NAME
fotowire.pl \- command-line client for the FotoWire protocol
.SH SYNOPSIS
.B fotowire.pl
.sp
.BI "fotowire.pl { check | eval | send } " order

.SH DESCRIPTION
.B fotowire.pl
is a command-line client for the FotoWire protocol. FotoWire is a system that
allows to send digital pictures to a photogaphic laboratory in order to have
them printed. 

.SH INVOCATION
.B fotowire.pl
takes either no argument or a
.I command
and an
.IR "order file".

Running
.B fotowire.pl
without argument for the first time creates a 
.I .fotowire
directory in the user's home directory, and creates there a skeleton of the
.I fotowirerc
config file.

Running
.B fotowire.pl
while a config file exists will fetch from the server a list of available
laboratories and display them. The user can then choose a laboratory from
that list and specify its
.I ID
in the config file.

Running
.B fotowire.pl
while a laboratory is defined in the config file will fetch the
.I laboratory description
from the server, which contains contact information of the laboratory, a list
of the
.I pay methods
supported by the laboratory for paying the order, a list of the
.I products
sold by the laboratory, and a list of the
.I ship methods
proposed by the laboratory for delivering the products. The information from
these lists (i.e. the
.IR IDs
of the various items of the lists) is then used to create an
.IR "order file".

Once the
.I order file
has been created, one can use the following commands:
.TP
.BI "fotowire.pl check " order
This parses the
.IR "order file",
checks for syntax errors and conformity to the requirements of the laboratory
(e.g. minimum size of the picture) and prints a summary of the order.
.TP
.BI "fotowire.pl eval " order
This sends the order to the server for a price evaluation, and prints the
result.
.TP
.BI "fotowire.pl send " order
This sends the picture files to the server and prints a summary of the order
actually received by the server and information about the laboratory which
will process the order.

.SH ORDER FILE SYNTAX

The
.I order file
is composed of two parts: a
.I header
and a 
.IR "body",
which are separated by an 
.IR "empty line".

The
.I header
is composed of
.IR "keyword-value pairs",
one per line. The
.I keyword
and the
.I value
are separated by space(s) and/or tabulation(s).
The values are
.IR "integers".
The supported keywords are:
.TP
.B PayMethod
which specifies the method used for paying the order. The value is the ID of
the chosen
.I pay method
described in the matching section of the
.IR "laboratory description".
.TP
.B ShipMethod
which specifies the method used for delivering the products. The value is the
ID of the chosen
.I ship method
described in the matching section of the
.IR "laboratory description".
.PP
The
.I body
is composed of
.IR "items",
one per line. The structure of an
.I item
is as follows:
.sp
.RS
.IR "ProductId Quantity File " [ "Options" ]
.RE
.sp
The components of the line are separated by space(s) and/or tabuation(s).
Here is a description of each element:
.TP
.I ProductId
is the
.I ID
of the desired product, defined in the
.I product list
of the
.IR "laboratory description",
.TP
.I Quantity
is the number of copies of the picture which will be printed,
.TP
.I File
is the filename of the picture,
.TP
.I Options
are the 
.I options
applied to that picture when printing.
.RE
.PP

The
.I options
are the following:
.TP
.B nocrop
with this option, if the proportions of the chosen paper are different from
the one of the picture, the whole picture will be printed so that it uses as
much as possible of the paper's surface, and leaving white bands on the sides
of the picture. This is the default option.
.TP
.BI "crop " argument
With this option, if the proportions of the chosen paper  are different from
the one of the picture, only a part of the picture will be printed, so that it
uses the whole surface of the paper. The sides of the picture will be cropped.
The
.I argument
is a percentage, positive or negative, that indicates what part of the picture
will appear on the paper. A value of 0 means that the central part of the
picture will be printed, a value of 100 means that the topmost or leftmost
(depending on the orientation) part of the picture will be printed, whereas
a value of -100 means that the bottommost or rightmost part of the picture
will be printed. Integet values between 0 and 100 are allowed and define what
proportion of the top (resp. left) and bottom (resp. right) will be removed.

.SH CONFIGURATION FILE SYNTAX
The
.I configuration file
is a Perl include script setting the following variables:
.TP
.B $lab_ID
Scalar variable, which contains the
.I ID
of the chosen
.IR "laboratory".
.TP
.B $promo_code
Scalar variable, which contains a
.I promotional code
given by the laboratory to the faithful customers.
.TP
.B %customer_info
Hash table, which contains information about the user.
.TP
.B %card_info
Hash table, which contains information about the user's credit card.
.PP

The
.I configuration file
ends with "1;" on a single line, for Perlish reasons.

The fields of
.B %customer_info
are:
.TP
.B Title
Mr., Mrs. or Ms.
.TP
.B FirstName, LastName
Customer's first name and last name,
.TP
.B Address1, Address2, City, StateOrProvince, PostalCode
Customer's address, city, state or province (if applicable) and postal (zip)
code,
.TP
.B CountryCode
Customer's country code, on 3 positions, as defined in the ISO XXX standard,
.TP
.B PhoneNumber, FaxNumber
Customer's phone and fax numbers,
.TP
.B EmailAddress
Customer's e-mail address. Don't forget to escape the @ character!
.TP
.B LabCustomerID
The customer ID given to the customer by the laboratory (if any),
.TP
.B DenyEmail
Set it to 1 if you don't want the laboratory to send you advertisement e-mail,
or set to to 0 otherwise.
.PP

The fields of
.B %card_info 
are:
.TP
.B Number
Credit card number,
.TP
.B ExpirationMonth, ExpirationYear
Credit card expiration month and year,
.TP
.B OwnerName
Credit card owner's name,
.PP
These 4 fields have not been tested so far, they might be wrongly used in the
software. Use at your own risks. You are warned.

.SH FILES
.I $HOME/.fotowire/fotowirerc
.RS
The configuration file
.RE

.SH ORDER FILE EXAMPLE
The following example uses the pay method 42 and ship method 24 of the chosen
laboratory, and then orders prints of 3 different pictures:
.HP
3 copies of
picture "Picture001.jpg" using product number 7,
.HP
1 copy of picture
"Picture002.jpg" using product number 8, cropping the picture so that the
cropped area is removed equaly from the top and from the bottom of the picture,
.HP
1 copy of picture "Picture003.jpg" using product number 8, cropping the
picture so that 1/4 of the cropped area is removed from the top of the
picture, and 3/4 of the cropped area is removed from the bottom. +50 means
that the printable area is shifted up by 50% of the distance between the top
of the default printed area (when centered) and the top of the picture.
.PP
-- cut here ---------------------- cut here --------
.RE
PayMethod 42
.RE
ShipMethod 24

7 3 Picture001.jpg
.RE
8 1 Picture002.jpg crop
.RE
8 1 Picture003.jpg crop +50

.SH BUGS
Probably a lot, since it has not (yet) been fully tested, the crop parameter
explanation is terrible. And the syntax is not very newbie-friendly.

.SH AUTHOR
Matthieu Weber <mweber@mit.jyu.fi>

.SH SEE ALSO
.BR Perl (1), 
.BR Crypt::SSLeay (3),
.BR HTTP::Request::Common (3),
.BR Image::Info (3),
.BR LWP::UserAgent (3),
.BR Unicode::MapUTF8 (3),
.BR URI (3),
.BR XML::Twig (3)
.RE
If these Perl modules don't come with your Linux distribution, see your local
CPAN mirror.
