Provided by: hylafax-client_6.0.7-5build1_amd64 bug

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 hierarchy.  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 executable script named T/S in the converter
       hierarchy.  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(5).  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(5) 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   /etc/hylafax/hyla.conf,
       /etc/hylafax/sendmail.conf,  /etc/hylafax/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/fonts/type1/gsfonts.

       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/sbin/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
                      /etc/hylafax/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
       /etc/hylafax/pagesizes       page size database
       /etc/hylafax/faxmail.ps      POSTSCRIPT prologue
       /etc/hylafax/hyla.conf       system-wide configuration file
       /etc/hylafax/faxmail.conf    system-wide configuration file
       /etc/hylafax/sendfax.conf    system-wide configuration file for direct delivery
       /usr/sbin/faxmail            hierarchy for external MIME converters
       /usr/share/fonts/type1/gsfontsfor font metrics
       /var/spool/hylafax/tmp/faxmailXXXXXXtemporary files

SEE ALSO

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

                                          July 22, 1996                                FAXMAIL(1)