1FAXMAIL(1)                  General Commands Manual                 FAXMAIL(1)
2
3
4

NAME

6       faxmail - HylaFAX mail-to-fax gateway application
7

SYNOPSIS

9       faxmail [ -O config ] [ options ] [ destination [ from ] ]
10

DESCRIPTION

12       faxmail takes an electronic mail message on standard input and converts
13       it to POSTSCRIPT® in a form that is suitable for transmission as a fac‐
14       simile.   The converted document is either written to the standard out‐
15       put or, if direct delivery is enabled, it is submitted  directly  to  a
16       HylaFAX server for transmission.
17
18       faxmail  is designed for use in constructing electronic mail to facsim‐
19       ile gateway services.  For example, mail  aliases  may  be  created  to
20       automatically transmit electronic mail; e.g.
21
22            sam: "|/usr/bin/faxmail -d sam@5551212"
23       or  faxmail  may  be used as a ``mail transport agent'', extracting the
24       necessary delivery information directly from the envelope of  the  mail
25       message.
26
27       If  faxmail  is  invoked  without enabling direct delivery then it just
28       formats the mail message on the standard input and writes the result to
29       the  standard  output.  To enable direct delivery the -d option must be
30       specified on the command line; see below for more information.
31

FORMATTING

33       faxmail formats a mail message according to the following rules:  First
34       it  parses the envelope information interpreting any meta-header infor‐
35       mation (see below) that is present.  Once the entire envelope has  been
36       collected it emits a formatted set of header lines if the -N option has
37       not been used.  By default all header information except the  ``From'',
38       ``To'',  ``Cc'', ``Subject'', and ``Date'' lines are discarded.  Header
39       lines that are kept have the tag (the string to the left of the  ``:'')
40       set in a bold font and the value (the string to the right of the ``:'')
41       set in an italic font.  Mail messages that conform to the  Multipurpose
42       Internet  Mail  Extensions  (MIME) specification are parsed and handled
43       according to the rules given below.  Plain text body parts  of  a  mail
44       message  are  formatted  in  a text font with any long lines wrapped at
45       word boundaries unless the -c option has been specified.
46
47       By default, faxmail sets all text in 10 point type on an  8.5"  by  11"
48       portrait-oriented  page  with  .35"  top margin, .25" bottom margin and
49       .25" left and right hand margins.  There are  command-line  options  to
50       control  the point size, page dimensions, orientation, and multi-column
51       formatting.  Text formatting can also be controlled through meta-header
52       directives placed in the envelope of the mail message.
53

ENVELOPE PROCESSING

55       faxmail  pre-processes the envelope information (i.e. the header lines)
56       before formatting the message contents.  Header lines whose names begin
57       with  ``X-FAX-''  (case-insensitive)  are  handled  specially-they  are
58       treated as command directives that specify how to generate  the  resul‐
59       tant  POSTSCRIPT  or, optionally, how to deliver the resulting document
60       as facsimile.  The set of known meta-headers corresponds to the set  of
61       configuration  parameters defined below.  A meta-header is specified as
62       ``X-FAX-parameter'' where parameter is  the  name  of  a  configuration
63       parameter;  e.g.  ``X-FAX-TabStop'' to set the number of spaces between
64       tab stops.
65
66       Controls for specifying headers to be passed through in  the  formatted
67       text  identify  not  only which headers but also the order in which the
68       headers should be emitted.  faxmail initializes the set of  headers  to
69       retain  to:  ``To  From Subject Cc Date''.  If this order is acceptable
70       then additional headers can simply  be  added  with  the  X-FAX-Headers
71       directive;  e.g. ``X-FAX-Headers: Message-id''.  If however a different
72       order is desired then the header set should be cleared with a ``clear''
73       header  tag  and  then  completely  specified in the desired order; for
74       example,
75
76       X-FAX-Headers: clear Message-id Date To Subject From Cc
77
78       will cause headers to be emitted in the order ``Message-Id Date To Sub‐
79       ject  From  Cc'' (depending on what headers are present).  Note in par‐
80       ticular that all header lines in the  envelope  can  be  suppressed  by
81       specifying  ``X-FAX-Headers: clear''; this is useful, for example, when
82       the body of the mail message contains a preformatted document  that  is
83       to be transmitted.
84
85       In  addition  to  the above controls, faxmail can also be instructed to
86       substitute an arbitrary string for a header  tag  when  generating  the
87       final  envelope.   This  facility  can  be used to better format ad-hoc
88       header information that is passed through the envelope of the  message.
89       The ``X-FAX-MapHeader'' meta-header specifies how to map a header line.
90       For example,
91
92       X-FAX-MapHeader: x_FAX_For Deliver FAX To
93
94       would cause any header ``x_FAX_For'' that appeared in the  envelope  to
95       be replaced in the formatted envelope by ``Deliver FAX To''.
96

MIME PROCESSING

98       faxmail parses MIME mail messages and does some rudimentary work to:
99
100       ·  strip out unprintable content such as audio, video, or binary data,
101
102       ·  decode encoded parts,
103
104       ·  insert ``digest dividers'' between multipart/digest subparts,
105
106       ·  format  message/rfc822  parts  as  described above for the top-level
107          envelope, and
108
109       ·  optionally convert graphical parts (e.g. images) for display.
110
111       MIME processing is fairly simple and (currently) somewhat  constrained.
112       faxmail  has built-in support for the following MIME parts: text/plain,
113       multipart/mixed,  multipart/digest,  message/rfc822,  application/post‐
114       script,  and application/x-faxmail-prolog.  Parts can also be processed
115       through external processing scripts that faxmail looks for in a  ``MIME
116       converters''   directory  hierarchy.   External  scripts  may  override
117       builtin processing or supplement the builtin support.   For  each  MIME
118       body  part  with  type T and subtype S faxmail checks first for an exe‐
119       cutable script named T/S in  the  converter  hierarchy.   If  a  script
120       exists  then  it is run and the result is appended as a new page to the
121       output PostScript document.  (The script is expected to  produce  inde‐
122       pendently  complete  pages.)  Otherwise if the part has builtin support
123       then it is processed directly.  Any part that does not have external or
124       builtin  support  is discarded and replaced by a message that indicates
125       the part was removed.  This discarded message can  be  suppressed  with
126       the MarkDiscarded configuration parameter (also settable with an X-FAX-
127       MarkDiscarded line in the envelope).
128
129       The built-in handling support is as follows: text/plain parts are  for‐
130       matted  using the default text font and point size; multipart/mixed are
131       ``burst'' and interpreted  per  the  specification  but  are  otherwise
132       unformatted;  multipart/digest  are  burst  and  an  optional  ``digest
133       divider'' marking may be inserted before each  subpart;  message/rfc822
134       are  formatted as described above with envelope header lines culled and
135       formatted with bold and italic fonts (in addition, if there is insuffi‐
136       cient space in the current output page/column for the message envelope,
137       optional divider, and one line of text,  then  faxmail  will  insert  a
138       ``break''  so  the  the message starts at the top of the next page/col‐
139       umn); application/postscript are copied through untouched to  the  out‐
140       put;  application/x-faxmail-prolog  are copied through untouched to the
141       end of the prologue section of the  generated  PostScript  document  to
142       permit customization of the formatted output.
143
144       faxmail supports the following Content-Transfer-Encoding schemes: 7bit,
145       8bit, binary, base64, quoted-printable, and x-uuencode.  Any  character
146       set that is not us-ascii is treated as iso-8859-1.
147
148       In general it is recommended that senders either permit faxmail to for‐
149       mat message contents or completely bypass the formatting facilities and
150       submit  data that is to be processed by sendfax.  Trying to combine the
151       two facilities by, for example, combining PostScript with text that  is
152       to be formatted is unlikely to work well because faxmail does not track
153       the amount of space on the page that a non-text MIME part uses.
154

DIRECT DELIVERY

156       When faxmail is invoked with the -d option it  delivers  the  formatted
157       document  directly  to  a HylaFAX server for transmission as facsimile.
158       Command line arguments may be supplied to specify the delivery destina‐
159       tion  and  sender identity; typically from information extracted by the
160       mail transport facility.  A command line destination is specified  with
161       the  same  syntax  as  the argument for the -d option to the sendfax(1)
162       command.  Similarly any from identity specified  on  the  command  line
163       follows  the same rules as the -f option to sendfax.  An explicit dial‐
164       string to use in delivery can also be  specified  with  an  X-FAX-Dial‐
165       string  header  in the mail message envelope.  If no sender identity is
166       provided on the command line then faxmail  will  extract  it  from  the
167       ``From''  line  in the envelope.  faxmail will not submit a message for
168       delivery if either the dialstring or  sender  identity  is  missing  or
169       null.
170
171       When  direct delivery is enabled X-FAX- header lines may be included in
172       the mail message  envelope  to  control  the  submission  and  delivery
173       process.   As  above  these  lines are specified as ``X-FAX-parameter''
174       where parameter is the name of a configuration parameter for the  send‐
175       fax program; e.g.  ``X-FAX-VRes'' to set the vertical resolution of the
176       transmitted facsimile.  By default automatic cover page  generation  is
177       enabled  when  direct delivery is used; this can be overridden with the
178       -n option on the command line or by  including  an  X-FAX-AutoCoverPage
179       header in the message envelope.
180

OPTIONS

182       -1        Set text in one column (default).
183
184       -2        Set text two columns.
185
186       -b font   Make  font, a POSTSCRIPT font name, the ``bold font'' used to
187                 set header lines.  The default bold font is Helvetica-Bold.
188
189       -c        Clip long text lines instead of wrapping them at word  bound‐
190                 aries near page margins.
191
192       -C cover  Use the cover page template file specified by cover.
193
194       -d        Enable  direct  delivery of facsimile; the formatted document
195                 will be submitted directly to a HylaFAX server for  transmis‐
196                 sion as facsimile.  This option is similar to piping the out‐
197                 put of faxmail to the input of sendfax(8C) except when direct
198                 delivery  is  enabled  faxmail  interprets  ``x-fax-'' header
199                 lines in the envelope of the mail message to look for control
200                 information  to  use  in  delivering  the  facsimile  and, by
201                 default, no automatic cover page generation is done.
202
203       -f font   Make font, a POSTSCRIPT font name, the text font used to  set
204                 the body of mail messages.  The default text font is Courier.
205
206       -H height Use height as the height, in inches, of the output page.  The
207                 default page height is taken from the default page size.
208
209       -i font   Make font, a POSTSCRIPT font name, the ``italic  font''  used
210                 to  set  header lines.  The default italic font is Helvetica-
211                 Oblique.
212
213       -Ml=#,r=#,t=#,b=#
214                 Set the page margins; the default margins are: left and right
215                 .25 inch, top .35 inch, bottom .25 inch.
216
217       -n        Suppress  auto cover page generation when doing direct deliv‐
218                 ery.
219
220       -N        Suppress the formatting of envelope headers.
221
222       -O config Treat config as a configuration parameter specification  that
223                 is  interpreted  after  reading  the configuration file.  For
224                 example, ``-O Host:fax.example.com'' would set the Host  con‐
225                 figuration  parameter  to ``fax.example.com'', overriding any
226                 setting in the configuration file.
227
228       -p size   Set all text using size for the font point size.
229
230       -r        Set pages rotated by 90 degrees (in ``Landscape mode'').
231
232       -R        Set pages unrotated (in ``Portrait mode'').
233
234       -s size   Set the page size to use.  Cover pages are normally generated
235                 using  a system-default page size (usually letter-size pages,
236                 8.5" by 11", for sites in  North  America).   Alternate  page
237                 sizes  are  specified  symbolically  using either the name or
238                 abbreviation of an entry in the pagesizes(5F) database;  e.g.
239                 a3  (ISO  A3), a4 (ISO A4), a5 (ISO A5), a6 (ISO A6), b4 (ISO
240                 B4), na-let (North American Letter), us-leg (American Legal),
241                 us-led (American Ledger), us-exe (American Executive), jp-let
242                 (Japanese Letter), and jp-leg (Japanese Legal).   Comparisons
243                 are case-insensitive and any match of a substring of the full
244                 page-size name is  sufficient;  e.g.  ``legal''  would  match
245                 ``American Legal''.
246
247       -S tsi    Pass tsi to the server as the suggested sender identification
248                 to be used, for example, in tagline imaging and fax protocol.
249
250       -t when   Notify the sender of  job  status  according  to  when.   The
251                 options    are    ``done'',    ``req''    (for    re-queued),
252                 ``none''/``off'', or ``default''.
253
254       -T        Trim leading blank lines on text parts.
255
256       -u user   Set the user name to use when logging in to do direct  deliv‐
257                 ery.   By  default the user is specified by the MailUser con‐
258                 figuration parameter (see below).  If a  null  user  name  is
259                 specified,  then  the  facsimile  will be submitted using the
260                 identity of the user that invoked faxmail.  On  the  command-
261                 line,  the  login password may also be provided by separating
262                 it  from  the  owner  login   name   with   a   colon,   like
263                 ``owner:pass''.
264
265       -v        Enable tracing of envelope, MIME, and job submission process‐
266                 ing.  Diagnostic information is written to the standard error
267                 (envelope  and MIME processing) and standard output (job sub‐
268                 mission).
269
270       -W width  Use width as the width, in inches, of the output  page.   The
271                 default page width is taken from the default page size.
272

CONFIGURATION PARAMETERS

274       faxmail    reads    configuration    information    from    the   files
275       /etc/hylafax/hyla.conf, /etc/hylafax/faxmail.conf,  and  ~/.hylarc;  in
276       that  order.   Configuration  files follow the conventions described in
277       hylafax-client(1).  The following configuration parameters  are  recog‐
278       nized:
279       Tag               Type         Default              Description
280       AutoCoverPage     boolean      Yes                  automatically generate cover page
281       BoldFont          string       Helvetica-Bold       font for setting header tags
282       Columns           integer      1                    number of columns in formatted output
283       DigestDivider     string       -                    multipart/digest divider POSTSCRIPT command
284       FirstAlternativeOnly           boolean              Yesonly use the first alternative part
285       FontPath          string       see below            directory for font metric files
286       GaudyHeaders      boolean      No                   enable/disable gaudy page headers
287       Headers           string       see below            headers to retain in envelope
288       ISO8859           boolean      Yes                  use ISO 8859-1 character encoding
289       ItalicFont        string       Helvetica-Oblique    font for setting header values
290       LineWrap          boolean      Yes                  wrap/truncate text lines
291       MailUser          string       -                    user identity for doing direct delivery
292       MarkDiscarded     boolean      Yes                  mark discarded MIME body parts
293       MapHeader         string       -                    define header mapping
294       MIMEConverters    string       see below            pathname of MIME converter scripts
295       Orientation       string       portrait             orientation of text on page
296       OutlineMargin     inches       0                    width of outline line
297       Overstrike        boolean      No                   overstrike interpretation of lone carriage returns
298       PageCollation     string       forward              collate pages in forward or reverse direction
299       PageHeaders       boolean      Yes                  enable/disable page headers
300       PageHeight        float        -                    output page height
301       PageMargins       string       see below            margins for formatted page
302       PageSize          string       default              output page size from database
303       PageWidth         float        -                    output page width
304       Prologfile        string       see below            pathname of POSTSCRIPT prologue file
305       TabStop           integer      8                    inter-stop setting in characters
306       TextFont          string       Courier              name of font for setting text
307       TextLineHeight    inches       -                    text formatting line height control
308       TextPointSize     inches       see below            size to use in setting text
309       TrimText          boolean      No                   trim leading blank lines on text parts
310       UseAlternativePart             integer              1which part to use in a set of alternatives
311       Verbose           boolean      No                   trace envelope and MIME processing
312
313       Values  marked  as  inches are specified using a syntax that identifies
314       one of several possible units:
315              #.##bp    big point (1in = 72bp)
316              #.##cc    cicero (1cc = 12dd)
317              #.##cm    centimeter
318              #.##dd    didot point (1157dd = 1238pt)
319              #.##in    inch
320              #.##mm    millimeter (10mm = 1cm)
321              #.##pc    pica (1pc = 12pt)
322              #.##pt    point (72.27pt = 1in)
323              #.##sp    scaled point (65536sp = 1pt)
324
325       Unit names can be upper or lower case but no white space  is  permitted
326       between  the  number  and  the unit.  Values specified with no unit are
327       interpreted as points.
328
329       The configuration parameters are explained below.  Most parameters cor‐
330       respond to a command line option.  Parameter values identified above as
331       inches are converted according to the conventions described above.
332
333       AutoCoverPage  Control whether or not a  cover  page  is  automatically
334                      generated for each job.
335
336       BoldFont       The name of the font to use to set header tags (i.e. the
337                      string to the left of the ``:'').
338
339       Columns        The number of columns to set text  in.   (Equivalent  to
340                      the -m option.)
341
342       DigestDivider  The  string to emit in the output before each subpart of
343                      a multipart/digest mail message.  This string  is  typi‐
344                      cally  a  POSTSCRIPT procedure that draws a mark of some
345                      sort.  Dividers are expected to  use  no  more  vertical
346                      space on the output page than a line of text.
347
348       FirstAlternativeOnly, UseAlternativePart
349                      In  a  multipart/alternative MIME section whether or not
350                      to only format the first part.  A  multipart/alternative
351                      MIME  section  is  typically  used  to  present the mail
352                      client with a selection of  alternatives  which  contain
353                      the  same  basic  content  (such  as  a text/plain and a
354                      text/html part).  Thus the mail client has the  opportu‐
355                      nity  to  select  which part is best-suited for its pur‐
356                      pose.  Generally the most-portable  format  (text/plain)
357                      is  the first alternative.  These options allow parts to
358                      be stripped when presented  in  a  multipart/alternative
359                      section  and prevents duplicate parts from being format‐
360                      ted.  ``FirstAlternativeOnly: true'' is synonymous  with
361                      ``UseAlternativePart:  1'' while ``FirstAlternativeOnly:
362                      false'' is  synonymous  with  ``UseAlternativePart:  0''
363                      (which  causes  all  alternatives  to be formatted).  In
364                      order to format only the text/html part then ``UseAlter‐
365                      nativePart: 2'' should work.
366
367       FontPath       The  path  where  Adobe  Font  Metric  (AFM)  files  are
368                      located;       by       default        /usr/share/ghost‐
369                      script/Resource/Init:/usr/share/ghost‐
370                      script/lib:/usr/share/ghost‐
371                      script/Resource/Font:/usr/share/ghost‐
372                      script/fonts:/usr/share/fonts/urw-
373                      base35:/usr/share/fonts/google-droid.
374
375       GaudyHeaders   Control whether or not to use a gaudy-style page header.
376                      Enabling gaudy headers implicitly enables page headers.
377
378       Headers        Define the headers retained from the envelope and  spec‐
379                      ify the order that they should be emitted in the format‐
380                      ted output.  The set of headers is initialized  to  ``To
381                      From  Subject Cc Date''.  Headers specified are appended
382                      to this list except for a ``clear'' header  that  causes
383                      the current set of headers to be discarded.
384
385       ISO8859        Control  the use of ISO 8859-1 encoding in the generated
386                      POSTSCRIPT
387
388       ItalicFont     The name of the font to use to set header  values  (i.e.
389                      the string to the right of the ``:'').
390
391       LineWrap       Control whether long text lines are wrapped or truncated
392                      at  the  right  hand  margin.   (Equivalent  to  the  -c
393                      option.)
394
395       MailUser       The  account  name  to use to login to a fax server when
396                      doing direct delivery.  Note that this account  name  is
397                      not used for the identity of the sender; this comes from
398                      the command line or the ``From'' line in the  mail  mes‐
399                      sage.   If  a  null  account name is specified, then the
400                      facsimile will be submitted using the  identity  of  the
401                      user that invoked faxmail.
402
403       MapHeader      Define  a  substitution  for  the  specified header that
404                      should be done each time the header is  emitted  in  the
405                      formatted  envelope.  Header tags are matched in a case-
406                      insensitive manner.
407
408       MarkDiscarded  Control whether discarded MIME parts are replaced  by  a
409                      text   message   indicating  the  original  content  was
410                      removed.
411
412       MIMEConverters The pathname of a directory hierarchy that  has  scripts
413                      for external processing of MIME body parts.  The default
414                      pathname is /etc/hylafax/faxmail.   HylaFAX  comes  with
415                      default converter scripts for TIFF and PDF, and they can
416                      be found in that path and used as a reference  for  con‐
417                      structing  other  converters.   The script is passed the
418                      filename of the body part for conversion  as  the  first
419                      argument.   Subsequent  arguments  are the MIME Content-
420                      Description, Content-ID,  Content-Disposition,  Content-
421                      Type  name, and Content-Disposition filename information
422                      which are each preceded by their respective  ``-descrip‐
423                      tion'',   ``-id'',   ``-disposition'',   ``-name'',   or
424                      ``-filename'' argument.
425
426       Orientation    Control whether pages are oriented horizontally (``land‐
427                      scape'')  or  vertically (``portrait'').  (Equivalent to
428                      the -r and -R options.)
429
430       OutlineMargin  Control whether columns of text have a line drawn around
431                      them  and the width of the line.  Setting this parameter
432                      to 0 disables outlines.
433
434       PageCollation  Control whether the output file has  pages  collated  in
435                      the  same  order  as  the input file (``forward'') or in
436                      reverse order (``reverse).
437
438       PageHeaders    Control whether page headers are generated.
439
440       PageHeight     Set the output page height (in inches).
441
442       PageMargins    Set the output page margins.  Margins are  specified  as
443                      string  of  the  form: ``l=#,r=#,t=#,b=#'' where l indi‐
444                      cates the left margin, r indicates the right  margin,  t
445                      indicates the top margin, b indicates the bottom margin,
446                      and numbers are interpreted as inches.   (Equivalent  to
447                      the -M option.)
448
449       PageSize       Set  the output page dimensions by name.  (Equivalent to
450                      the -s option.)
451
452       PageWidth      Set the output page width (in inches).
453
454       PrologFile     The pathname of a file containing POSTSCRIPT that should
455                      be  included  in  the  prologue section of the generated
456                      POSTSCRIPT.     The    default    prologue    file    is
457                      /etc/hylafax/faxmail.ps.
458
459       TabStop        Set the tab stop distance (in characters).
460
461       TextFont       Set  the name of font to use for setting text.  (Equiva‐
462                      lent to the -f option.)
463
464       TextLineHeight Set the vertical text line height and spacing.
465
466       TextPointSize  Set the  point  size  to  use  in  setting  plain  text.
467                      (Equivalent to the -p option.)
468
469       TrimText       Trim leading blank lines on text parts.
470
471       Verbose        Control tracing envelope and MIME processing.
472

NOTES

474       Because a sender's identity in an electronic mail message is inherently
475       untrustworthy, using faxmail to build a mail to fax gateway is problem‐
476       atic.   Unless mail service is somehow restricted or the sender's iden‐
477       tity is verified using a mechanism such as RFC 1847's  multipart/signed
478       MIME  type  there  is  no reliable way to restrict access to facilities
479       setup with faxmail.
480

BUGS

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

FILES

487       ~/.hylarc                    per-user configuration file
488       /etc/hylafax/pagesizes       page size database
489       /etc/hylafax/faxmail.ps      POSTSCRIPT prologue
490       /etc/hylafax/hyla.conf       system-wide configuration file
491       /etc/hylafax/faxmail.conf    system-wide configuration file
492       /etc/hylafax/sendfax.conf    system-wide configuration file for direct delivery
493       /etc/hylafax/faxmail         hierarchy for external MIME converters
494       /usr/share/ghostscript/Resource/Init:/usr/share/ghostscript/lib:/usr/share/ghostscript/Resource/Font:/usr/share/ghostscript/fonts:/usr/share/fonts/urw-base35:/usr/share/fonts/google-droidfor font metrics
495       /var/spool/hylafax/tmp/faxmailXXXXXXtemporary files
496

SEE ALSO

498       hylafax-client(1), textfmt(1), sendfax(1)
499
500
501
502                                 July 22, 1996                      FAXMAIL(1)
Impressum