.\"	$Id$
.\"
.\" HylaFAX Facsimile Software
.\"
.\" Copyright (c) 1993-1996 Sam Leffler
.\" Copyright (c) 1993-1996 Silicon Graphics, Inc.
.\" HylaFAX is a trademark of Silicon Graphics
.\" 
.\" Permission to use, copy, modify, distribute, and sell this software and 
.\" its documentation for any purpose is hereby granted without fee, provided
.\" that (i) the above copyright notices and this permission notice appear in
.\" all copies of the software and related documentation, and (ii) the names of
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
.\" publicity relating to the software without the specific, prior written
.\" permission of Sam Leffler and Silicon Graphics.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
.\" 
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
.\" OF THIS SOFTWARE.
.\"
.if n .po 0
.ds Fx \fIHyla\s-1FAX\s+1\fP
.TH PAGESIZES 5 "December 5, 1994"
.SH NAME
pagesizes \- \*(Fx page size definitions
.SH DESCRIPTION
The
.I pagesizes
database defines the page dimensions and guaranteed reproducible
areas (\s-1GRA\s+1) for well-known page sizes.
The 
.SM GRA
is the portion of the page that is guaranteed to be imaged during
facsimile transmission.
This region is typically less than the full page dimensions because
of paper roller contacts and other mechanical aspects of the printing
process in a facsimile machine.
.PP
All \*(Fx
programs that require page size information read the information
from this database using a page size name.
Documents should be prepared such that the full page dimensions are
employed with the imaged area contained within the 
.SM GRA.
.PP
The system-wide default page size to use in preparing documents
for transmission
is given by the ``\fIdefault\fP'' entry in the database.
(NB: the default entry should be placed
last so that inverse matches find the real page size name and not
the default entry.)
.PP
The page size database is an
.SM ASCII
file with the following format.
Each entry consists of whitespace-separated fields:
.nf
.sp .5
\fCname  abbrev  width  height  gra-width  gra-height  top-margin  left-margin\fP
.sp .5
.fi
Fields have the following interpretation:
.TP 12
.B name
the full name for the page size; e.g. \s-1ISO A4\s+1;
.TP
.B abbrev
an abbreviated version of the full name for use in compact listings such
as the receive queue listing printed by
.IR faxstat (1);
.TP
.B width
the full width of the page;
.TP
.B height
the full height of the page;
.TP
.B gra-width
the width of the
.SM GRA;
.TP
.B gra-height
the height of the
.SM GRA;
.TP
.B top-margin
the margin between the top of the full page and the top of the
.SM GRA;
.TP
.B left-margin
the margin between the left side of the full page the left side of the
.SM GRA.
.PP
The first two fields must be separated from the subsequent fields by
a tab character (possibly followed by more whitespace); this is done
to easily permit blank characters to be included in names.
Otherwise fields can be separated by any amount of any kind of whitespace.
Numbers are all base 10 and in basic measurement units (\s-1BMU\s+1);
defined as 1/1200 x 25.4 millimeters for paper output with a scale factor
of one.
All fields must be present on a single line; otherwise the entry
is ignored.
Comments are introduced by the ``#'' character and continue
to the end the line.
.PP
Page size database lookups are either by name or by page dimensions.
Lookups by name are done by sequentially scanning the entries in
the database for the first entry that has a matching 
abbreviation or substring of the page size name field.
The string comparisons ignore case so,
for example, ``a4'' would match a full name of ``\s-1ISO A4\s+1''.
Lookups by dimension scan the entire database and return the
page with the closest dimensions using a straightforward distance metric.
If the difference in dimensions of the closest match is greater than
1/2 inch on each side, then no page entry is returned for a lookup by
dimension.
.SH "SEE ALSO"
.IR hylafax-client (1),
.IR faxmail (1),
.IR faxstat (1),
.IR sendfax (1),
.IR sgi2fax (1),
.IR textfmt (1).