faxmail

FAXMAIL(1)                   General Commands Manual                  FAXMAIL(1)



NAME
       faxmail - HylaFAX mail-to-fax gateway application

SYNOPSIS
       faxmail [ options ] [ destination [ from ] ]

DESCRIPTION
       faxmail takes an electronic mail message on standard input and submits it
       as a facsimile to a HylaFAX server for transmission.

       faxmail is designed for use in constructing electronic mail to facsimile
       gateway services.  For example, mail aliases may be created to
       automatically transmit electronic mail; e.g.

            sam: "|/usr/bin/faxmail sam@5551212"
       or faxmail may be used as a ``mail transport agent'', extracting the
       necessary delivery information directly from the envelope of the mail
       message.

FORMATTING
       faxmail formats a mail message according to the following rules: First it
       parses the envelope information interpreting any meta-header information
       (see below) that is present.  Once the entire envelope has been collected
       it emits a formatted set of header lines.  By default all header
       information except the ``From'', ``To'', ``Cc'', ``Subject'', and
       ``Date'' lines are discarded.  Header lines that are kept have the tag
       (the string to the left of the ``:'') set in a bold font and the value
       (the string to the right of the ``:'') set in an italic font.  Mail
       messages that conform to the Multipurpose Internet Mail Extensions (MIME)
       specification are parsed and handled according to the rules given below.
       Plain text body parts of a mail message are formatted in a text font with
       any long lines wrapped at word boundaries unless the -c option has been
       specified.

       By default, faxmail sets all text in 10 point type on an 8.5" by 11"
       portrait-oriented page with .35" top margin, .25" bottom margin and .25"
       left and right hand margins.  There are command-line options to control
       the point size, page dimensions, orientation, and multi-column
       formatting.  Text formatting can also be controlled through meta-header
       directives placed in the envelope of the mail message.

ENVELOPE PROCESSING
       faxmail pre-processes the envelope information (i.e. the header lines)
       before formatting the message contents.  Header lines whose names begin
       with ``X-FAX-'' (case-insensitive) are handled specially-they are treated
       as command directives that specify how to generate the resultant
       POSTSCRIPT or, optionally, how to deliver the resulting document as
       facsimile.  The set of known meta-headers corresponds to the set of
       configuration parameters defined below.  A meta-header is specified as
       ``X-FAX-parameter'' where parameter is the name of a configuration
       parameter; e.g.  ``X-FAX-TabStop'' to set the number of spaces between
       tab stops.

       Controls for specifying headers to be passed through in the formatted
       text identify not only which headers but also the order in which the
       headers should be emitted.  faxmail initializes the set of headers to
       retain to: ``To From Subject Cc Date''.  If this order is acceptable then
       additional headers can simply be added with the X-FAX-Headers directive;
       e.g. ``X-FAX-Headers: Message-id''.  If however a different order is
       desired then the header set should be cleared with a ``clear'' header tag
       and then completely specified in the desired order; for example,

       X-FAX-Headers: clear Message-id Date To Subject From Cc

       will cause headers to be emitted in the order ``Message-Id Date To
       Subject From Cc'' (depending on what headers are present).  Note in
       particular that all header lines in the envelope can be suppressed by
       specifying ``X-FAX-Headers: clear''; this is useful, for example, when
       the body of the mail message contains a preformatted document that is to
       be transmitted.

       In addition to the above controls, faxmail can also be instructed to
       substitute an arbitrary string for a header tag when generating the final
       envelope.  This facility can be used to better format ad-hoc header
       information that is passed through the envelope of the message.  The ``X-
       FAX-MapHeader'' meta-header specifies how to map a header line.  For
       example,

       X-FAX-MapHeader: x_FAX_For Deliver FAX To

       would cause any header ``x_FAX_For'' that appeared in the envelope to be
       replaced in the formatted envelope by ``Deliver FAX To''.

MIME PROCESSING
       faxmail parses MIME mail messages and does some rudimentary work to:

       •  decode encoded parts,

       •  formats the message and text parts into a Postscript document

       •  insert ``digest dividers'' between multipart/digest subparts,

       •  format message/rfc822 parts as described above for the top-level
          envelope, and

       •  submit all other attached documents to be faxed.

       MIME processing is fairly simple and (currently) somewhat constrained.
       faxmail has builtin support for the following MIME parts: text/plain,
       multipart/mixed, multipart/digest, message/rfc822,
       application/postscript, and application/x-faxmail-prolog.  Parts can also
       be processed through external processing scripts that faxmail looks for
       in a ``MIME converters'' directory hierachy.  External scripts may
       override builtin processing or suppliment the builtin support.  For each
       MIME body part with type T and subtype S faxmail checks first for an
       exceutable script named T/S in the converter heirarchy.  If a script
       exists then it is run and the resulting output is saved as a document
       submitted to HylaFAX.  If the output is empty, the part is suppressed,
       and will not be submitted.  All other parts will be saved as documents
       and submitted to HylaFAX.  faxmail uses the typerules(5F).  mechanism to
       convert file formats into one of the format HylaFAX supports.

       The builtin handling support is as follows: text/plain parts are
       formatted using the default text font and point size; multipart/mixed are
       ``burst'' and interpreted per the specification but are otherwise
       unformatted; multipart/digest are burst and an optional ``digest
       divider'' marking may be inserted before each subpart; message/rfc822 are
       formatted as described above with envelope header lines culled and
       formatted with bold and italic fonts (in addition, if there is
       insufficient space in the current output page/column for the message
       envelope, optional divider, and one line of text, then faxmail will
       insert a ``break'' so the the message starts at the top of the next
       page/column); application/postscript are copied through untouched to the
       output; application/x-faxmail-prolog are copied through untouched to the
       end of the prologue section of the generated PostScript document to
       permit customization of the formatted output.

       faxmail supports the following Content-Transfer-Encoding schemes: 7bit,
       8bit, binary, base64, quoted-printable, and x-uuencode.  Any character
       set that is not us-ascii is treated as iso-8859-1.

SERVER DELIVERY
       When faxmail is invoked it delivers the formatted document directly to a
       HylaFAX server for transmission as facsimile.  Command line arguments may
       be supplied to specify the delivery destination and sender identity;
       typically from information extracted by the mail transport facility.  A
       command line destination is specified with the same syntax as the
       argument for the -d option to the sendfax(1) command.  Similarly any from
       identity specified on the command line follows the same rules as the -f
       option to sendfax.  An explicit dialstring to use in delivery can also be
       specified with an X-FAX-Dialstring header in the mail message envelope.
       If no sender identity is provided on the command line then faxmail will
       extract it from the ``From'' line in the envelope.  faxmail will not
       submit a message for delivery if either the dialstring or sender identity
       is missing or null.

       X-FAX- header lines may be included in the mail message envelope to
       control the submission and delivery process.  As above these lines are
       specified as ``X-FAX-parameter'' where parameter is the name of a
       configuration parameter for the sendfax program; e.g.  ``X-FAX-VRes'' to
       set the vertical resolution of the transmitted facsimile.  By default
       automatic cover page generation is enabled when direct delivery is used;
       this can be overridden with the -n option on the command line or by
       including an X-FAX-AutoCoverPage header in the message envelope.

OPTIONS
       -1        Set text in one column (default).

       -2        Set text two columns.

       -b font   Make font, a POSTSCRIPT font name, the ``bold font'' used to
                 set header lines.  The default bold font is Helvetica-Bold.

       -c        Clip long text lines instead of wrapping them at page margins.

       -C cover  Use the cover page template file specified by cover.

       -f font   Make font, a POSTSCRIPT font name, the text font used to set
                 the body of mail messages.  The default text font is Courier.

       -H height Use height as the height, in inches, of the output page.  The
                 default page height is taken from the default page size.

       -i font   Make font, a POSTSCRIPT font name, the ``italic font'' used to
                 set header lines.  The default italic font is Helvetica-
                 Oblique.

       -Ml=#,r=#,t=#,b=#
                 Set the page margins; the default margins are: left and right
                 .25 inch, top .35 inch, bottom .25 inch.

       -n        Suppress auto cover page generation.

       -N        Suppress formatting of mail envelope headers.

       -p size   Set all text using size for the font point size.

       -r        Set pages rotated by 90 degrees (in ``Landscape mode'').

       -R        Set pages unrotated (in ``Portrait mode'').

       -s size   Set the page size to use.  Cover pages are normally generated
                 using a system-default page size (usually letter-size pages,
                 8.5" by 11", for sites in North America).  Alternate page sizes
                 are specified symbolically using either the name or
                 abbreviation of an entry in the pagesizes(5F) database; e.g.
                 a3 (ISO A3), a4 (ISO A4), a5 (ISO A5), a6 (ISO A6), b4 (ISO
                 B4), na-let (North American Letter), us-leg (American Legal),
                 us-led (American Ledger), us-exe (American Executive), jp-let
                 (Japanese Letter), and jp-leg (Japanese Legal).  Comparisons
                 are case-insensitive and any match of a substring of the full
                 page-size name is sufficient; e.g. ``legal'' would match
                 ``American Legal''.

       -t notify Specify the notify value to use

       -T        Trim leading blank lines from text parts.  If the text part is
                 completely empty, it will effectively be skipped.

       -u user   Set the user name to use when logging in to do direct delivery.
                 By default the user is specified by the MailUser configuration
                 parameter (see below).  If a null user name is specified, then
                 the facsimile will be submitted using the identity of the user
                 that invoked faxmail.

       -v        Enable tracing of envelope, MIME, and job submission
                 processing.  Diagnostic information is written to the standard
                 error (envelope and MIME processing) and standard output (job
                 submission).

       -W width  Use width as the width, in inches, of the output page.  The
                 default page width is taken from the default page size.

CONFIGURATION PARAMETERS
       faxmail reads configuration information from the files
       /usr/lib/fax/hyla.conf, /usr/lib/fax/sendmail.conf,
       /usr/lib/fax/faxmail.conf, and ~/.hylarc; in that order.  Configuration
       files follow the conventions described in hylafax-client(1).  In addition
       to the formatting configuration parameters below, all of the parameters
       listed in the sendfax(1) man page apply as well.

       The following configuration parameters are recognized to support
       formatting:
       Tag               Type         Default              Description
       AutoCoverPage     boolean      Yes                  automatically generate cover page
       BoldFont          string       Helvetica-Bold       font for setting header tags
       Columns           integer      1                    number of columns in formatted output
       DigestDivider     string       -                    multipart/digest divider POSTSCRIPT command
       FontPath          string       see below            directory for font metric files
       GaudyHeaders      boolean      No                   enable/disable gaudy page headers
       Headers           string       see below            headers to retain in envelope
       ISO8859           boolean      Yes                  use ISO 8859-1 character encoding
       ItalicFont        string       Helvetica-Oblique    font for setting header values
       LineWrap          boolean      Yes                  wrap/truncate text lines
       MailUser          string       -                    user identity for doing direct delivery
       MarkDiscarded     boolean      Yes                  mark discarded MIME body parts
       MapHeader         string       -                    define header mapping
       MIMEConverters    string       see below            pathname of MIME converter scripts
       Orientation       string       portrait             orientation of text on page
       OutlineMargin     inches       0                    width of outline line
       PageCollation     string       forward              collate pages in forward or reverse direction
       PageHeaders       boolean      Yes                  enable/disable page headers
       PageHeight        float        -                    output page height
       PageMargins       string       see below            margins for formatted page
       PageSize          string       default              output page size from database
       PageWidth         float        -                    output page width
       Prologfile        string       see below            pathname of POSTSCRIPT prologue file
       TabStop           integer      8                    inter-stop setting in characters
       TextFont          string       Courier              name of font for setting text
       TextLineHeight    inches       -                    text formatting line height control
       TextPointSize     inches       see below            size to use in setting text
       Verbose           boolean      No                   trace envelope and MIME processing

       Values marked as inches are specified using a syntax that identifies one
       of several possible units:
              #.##bp    big point (1in = 72bp)
              #.##cc    cicero (1cc = 12dd)
              #.##cm    centimeter
              #.##dd    didot point (1157dd = 1238pt)
              #.##in    inch
              #.##mm    millimeter (10mm = 1cm)
              #.##pc    pica (1pc = 12pt)
              #.##pt    point (72.27pt = 1in)
              #.##sp    scaled point (65536sp = 1pt)

       Unit names can be upper or lower case but no white space is permitted
       between the number and the unit.  Values specified with no unit are
       interpreted as points.

       The configuration parameters are explained below.  Most parameters
       correspond to a command line option.  Parameter values identified above
       as inches are converted according to the conventions described above.

       AutoCoverPage  Control whether or not a cover page is automatically
                      generated for each job.

       BoldFont       The name of the font to use to set header tags (i.e. the
                      string to the left of the ``:'').

       Columns        The number of columns to set text in.  (Equivalent to the
                      -m option.)

       DigestDivider  The string to emit in the output before each subpart of a
                      multipart/digest mail message.  This string is typically a
                      POSTSCRIPT procedure that draws a mark of some sort.
                      Dividers are expected to use no more vertical space on the
                      output page than a line of text.

       FontPath       The path where Adobe Font Metric (AFM) files are located;
                      by default /usr/share/ghostscript/fonts.

       GaudyHeaders   Control whether or not to use a gaudy-style page header.
                      Enabling gaudy headers implicitly enables page headers.

       Headers        Define the headers retained from the envelope and specify
                      the order that they should be emitted in the formatted
                      output.  The set of headers is initialized to ``To From
                      Subject Cc Date''.  Headers specified are appended to this
                      list except for a ``clear'' header that causes the current
                      set of headers to be discarded.

       ISO8859        Control the use of ISO 8859-1 encoding in the generated
                      POSTSCRIPT

       ItalicFont     The name of the font to use to set header values (i.e. the
                      string to the right of the ``:'').

       LineWrap       Control whether long text lines are wrapper or truncated
                      at the right hand margin.  (Equivalent to the -c option.)

       MailUser       The account name to use to login to a fax server when
                      doing direct delivery.  Note that this account name is not
                      used for the identity of the sender; this comes from the
                      command line or the ``From'' line in the mail message.  If
                      a null account name is specified, then the facsimile will
                      be submitted using the identity of the user that invoked
                      faxmail.

       MapHeader      Define a substitution for the specified header that should
                      be done each time the header is emitted in the formatted
                      envelope.  Header tags are matched in a case-insensitive
                      manner.

       MarkDiscarded  Control whether discarded MIME parts are replaced by a
                      text message indicating the original content was removed.

       MIMEConverters The pathname of a directory hierarchy that has scripts for
                      external processing of MIME body parts.  The default
                      pathname is /usr/lib/fax/faxmail.

       Orientation    Control whether pages are oriented horizontally
                      (``landscape'') or vertically (``portrait'').  (Equivalent
                      to the -r and -R options.)

       OutlineMargin  Control whether columns of text have a line drawn around
                      them and the width of the line.  Setting this parameter to
                      0 disables outlines.

       PageCollation  Control whether the output file has pages collated in the
                      same order as the input file (``forward'') or in reverse
                      order (``reverse).

       PageHeaders    Control whether page headers are generated.

       PageHeight     Set the output page height (in inches).

       PageMargins    Set the output page margins.  Margins are specified as
                      string of the form: ``l=#,r=#,t=#,b=#'' where l indicates
                      the left margin, r indicates the right margin, t indicates
                      the top margin, b indicates the bottom margin, and numbers
                      are interpreted as inches.  (Equivalent to the -M option.)

       PageSize       Set the output page dimensions by name.  (Equivalent to
                      the -s option.)

       PageWidth      Set the output page width (in inches).

       PrologFile     The pathname of a file containing POSTSCRIPT that should
                      be included in the prologue section of the generated
                      POSTSCRIPT.  The default prologue file is
                      /usr/lib/fax/faxmail.ps.

       TabStop        Set the tab stop distance (in characters).

       TextFont       Set the name of font to use for setting text.  (Equivalent
                      to the -f option.)

       TextLineHeight Set the vertical text line height and spacing.

       TextPointSize  Set the point size to use in setting plain text.
                      (Equivalent to the -p option.)

       Verbose        Control tracing envelope and MIME processing.

NOTES
       Because a sender's identity in an electronic mail message is inherently
       untrustworthy, using faxmail to build a mail to fax gateway is
       problematic.  Unless mail service is somehow restricted or the sender's
       identity is verified using a mechanism such as RFC 1847's
       multipart/signed MIME type there is no reliable way to restrict access to
       facilities setup with faxmail.

BUGS
       Only the last instance of a header is kept and written to the output.
       This means, for example, that only the last of many ``Received'' lines
       will be included in the formatted output.

FILES
       ~/.hylarc                    per-user configuration file
       /usr/lib/fax/pagesizes       page size database
       /usr/lib/fax/faxmail.ps      POSTSCRIPT prologue
       /usr/lib/fax/hyla.conf       system-wide configuration file
       /usr/lib/fax/faxmail.conf    system-wide configuration file
       /usr/lib/fax/sendfax.conf    system-wide configuration file for direct delivery
       /usr/lib/fax/faxmail         hierarchy for external MIME converters
       /usr/share/ghostscript/fonts for font metrics
       /var/spool/hylafax/tmp/faxmailXXXXXXtemporary files

SEE ALSO
       hylafax-client(1), textfmt(1), sendfax(1)



                                  July 22, 1996                       FAXMAIL(1)