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

NAME

       faxcover - generate a POSTSCRIPT cover page for an outgoing facsimile

SYNOPSIS

       faxcover [ options ] -f from-name -n fax-number

DESCRIPTION

       faxcover  generates  a  POSTSCRIPT® cover page document on the standard output.  The cover
       page fills the entire area of a default page and is created according to  the  information
       supplied on the command line and a cover sheet template file.

       faxcover  is  normally invoked by the sendfax(1) program to generate a cover page for each
       outgoing facsimile.

       faxcover works by creating a POSTSCRIPT  dictionary  that  contains  definitions  for  the
       variable  information  that  is to be placed on the facsimile cover page.  Specifically, a
       dictionary with the following symbols are defined:
       Symbol             Description                        Symbol               Description
       to                 destination person                 from                 sending person
       to-company         destination company                from-company         sender's company
       to-location        destination geographic location    from-location        sender geographic location
       to-voice-number    person's voice phone number        from-voice-number    sender's voice phone number
       to-fax-number      destination fax phone number       from-fax-number      sender's fax phone number
                                                             from-mail-address    sender's e-mail address
       comments           unbroken comment string            commentsX            X'th line of comments
       regarding          Re: subject                        CommentX             similar to commentsX
       pageWidth          page width in millimeters          page-count           # pages other than cover page
       pageLength         page length in millimeters         todays-date          current date and time

       If the comments string is longer than maxlencomments characters, it  is  broken,  on  word
       boundaries  or  instances of ``\n´´, into multiple POSTSCRIPT strings commentsX where X is
       the line number; e.g.  comments2 for the second line of comments.  Long substrings without
       whitespace  which exceed maxlencomments are also broken. By default faxcover will generate
       20 commentsX strings, emitting null string values for empty lines.   This  number  can  be
       changed  with the -m option; see below.  maxlencomments is changed with the -z option; see
       below.

       Note that use of commentsX with non-fixed-width fonts can lead to spatial  problems  where
       characters  run  off  the  edge  of  the  generated  cover  page.   In  such cases, use of
       BreakIntoLines (see below) may be a more suitable approach.

       CommentX is similar to commentsX except that its  values  are  created  only  by  breaking
       comments on instances of ``\n´´ and not otherwise.  maxlines does not affect CommentX

       faxcover  also  emits  a  POSTSCRIPT  procedure for breaking comment strings into multiple
       lines  using  the  POSTSCRIPT  font  metric  information.    This   procedure   is   named
       BreakIntoLines and has the following usage convention:

       %<line-width> <line-height> <x> <y> <string> BreakIntoLines -

       eg
              /rule (_____________________________________________) def
              /lw rule stringwidth pop def /lh 30 def
              /y 191.4 def /x 0 def
              y -30 0 { x exch moveto rule show } for
              lw lh x y comments BreakIntoLines
       where  the width of the rule controls the length of each line of comments (note that it is
       made slightly shorter here for the purpose of presentation), x and y  are  initialized  to
       coordinate locations on the page where the comment string should be imaged, and the number
       30 is the inter-line spacing appropriate for the font used to image the comment lines.

       If information is unavailable for an item, the associated POSTSCRIPT symbol is defined  to
       be a null string.

       Following  the  definition  prologue, a cover sheet template file is copied.  This file is
       expected to be a POSTSCRIPT program that uses the generated  strings  to  create  a  cover
       page.   The template must include a showpage operator to cause the page to be imaged.  The
       above symbols will be defined in the current  dictionary.   A  trailing  end  operator  is
       supplied by faxcover, so any manipulation of the dictionary stack should leave the current
       dictionary on the top of the stack on completion.

OPTIONS

       -c comments Use comments for the comment string. You may use '\n' to break it into several
                   lines on generated the cover page.

       -C file     Use   file  as  the  template  file.   The  default  template  file  is  named
                   faxcover.ps.  The template file can also be specified by setting the  FAXCOVER
                   environment  variable.   If the template filename is not an absolute pathname,
                   then faxcover looks first for this file in the home directory of  the  sender.
                   If  no  such file is present, then it looks in the library directory where the
                   HylaFAX client application  data  are  installed.   If  no  template  file  is
                   located, faxcover will terminate without generating a cover page.

       -D format   Use  format  as  the  formatting  specification  passed  to  strftime(3)  when
                   generating the time and date placed on the cover page.

       -f name     Use name for the sender's identity.

       -l location Use location for the geographic location of the destination company.

       -L location Use location for the geographic location of the sender's company.

       -m maxlines indicates the maximum number of commentsX lines to generate.

       -M address  Use address for the sender's e-mail address.

       -n number   Use number for the destination fax machine number.

       -N number   Use number for the sender's fax machine number.

       -p count    Use count for the count of pages to follow the cover page.

       -r regarding
                   Use regarding for the ``Re:'' field.

       -s size     Set the page size  to  use  for  the  transmitted  facsimile.   Facsimile  are
                   normally  imaged  with  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''.

                   Note  that  it  may  not  be permissible to image into the full page area; the
                   guaranteed reproducible area for a page is typically inset.  Also,  note  that
                   while  arbitrary  page  sizes can be specified through the page size database,
                   only a limited set of page dimensions are supported by the Group  3  facsimile
                   protocol.   Thus if an odd-size facsimile is submitted for transmission it may
                   not be possible  to  determine  if  it  can  be  sent  until  the  fax  server
                   establishes communication with the remote facsimile machine.

       -t name     Use name for the receiver's identity.

       -v number   Use number for the receiver's voice phone number.

       -V number   Use number for the sender's voice phone number.

       -x company  Use company for the destination company name.

       -X company  Use company for the sender's company name.

       -z maxlencomments
                   indicates  the  maximum  length in number of characters allowed in a commentsX
                   string.

DIAGNOSTICS

       Complaints about not being able to locate a template file.

FILES

       ~/.faxdb                    personal fax number database
       ~/.hylarc                   per-user configuration file
       /etc/hylafax/hyla.conf      system-wide configuration file
       /etc/hylafax/faxcover.ps    default cover page template
       /etc/hylafax/pagesizes      page size database

BUGS

       faxcover should be able to determine the appropriate length of commentsX strings by  using
       font metric information.

SEE ALSO

       hylafax-client(1), sendfax(1) edit-faxcover(1)

                                         January 06, 2001                             FAXCOVER(1)