Provided by: hylafax-client_6.0.5-5ubuntu3_i386 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:

       o  decode encoded parts,

       o  formats the message and text parts into a Postscript document

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

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

       o  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(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)