  tsfax
  Harald Milz, hhmm@@sseenneeccaa..mmuucc..ddee
  08 Oct 1996

  This is the README for my Emacs TeX-fax-mode called ttssffaaxx--00..9900 -- a
  XEmacs / LaTeX-mode frontend for mgetty+sendfax. Copyright: (c) 1995,
  1996 Harald Milz

  11..  IInnttrroodduuccttiioonn


  ttssffaaxx is a Xemacs / LaTeX-Mode frontend for Gert Doering
  <mmaaiillttoo::ggeerrtt@@ggrreeeenniiee..mmuucc..ddee>'s mgetty+sendfax package (more exactly,
  to ffaaxxssppooooll which is the "working horse" in this package).

  It is still a BETA release.  You must have LaTeX 2.09 and xdvi-18 (or
  later) installed.  The package has been tested successfully with Lucid
  Emacs 19.10 and XEmacs 19.11/19.13 on Linux 1.1, 1.2 and 2.0 and with
  XEmacs 19.11 on AIX 4.1. I don't know whether the package works with
  later versions of LaTeX or with GNU Emacs too (can someone please try
  it out?).

  The package is copyrighted according to the GNU Public License Version
  2.0 (or later, whichever applies). Read the file COPYING for details.



  22..  WWhhyy jjuusstt aannootthheerr ffaaxx ffrroonntteenndd??


  tsfax makes use of Emacs' tteexx--mmooddee (llaatteexx--mmooddee, actually) so that you
  can write nice faxes in LaTeX, using a derivative of the LaTeX
  ddiinnbbrriieeff..ssttyy style. This is very handy once you get used to using
  LaTeX. There are two pluses compared to other fax frontends:


  +o  you can attach multiple files in various formats

  +o  you can transparently mail the fax to a remote fax server



  33..  DDeessiiggnn


  The stuff makes use of a modified version of ddiinnbbrriieeff..ssttyy, called
  ffaaxx..ssttyy (actually, I just omitted some items such as the placement of
  the sender's address and placed the date line below the address box.
  The sender's line for the envelope window is missing too because
  that's not needed here).

  Now if you write such a fax, you can make use of all ddiinnbbrriieeff..ssttyy
  features (except those listed above).  Plus, you can append arbitrary
  pages to your fax (which isn't limited in terms of page numbers). So
  if you want to send your friend a short and friendly fax and want to
  send a screenshot of your fancy new X11 tool, you simply say



       %APPEND "<filename-of-screenshot>"
       %APPEND '<next-file>'





  somewhere in the TeX file. You are limited to the file formats that
  ffaaxxssppooooll recognizes (well, those are quite a few). You might want to
  care for proper file name extensions because this makes it easier for
  ffaaxxssppooooll to choose the correct conversion tool. Unfortunately,
  ffaaxxssppooooll still isn't too smart when it comes to automatic file type
  recognition. E.g. if you want to append a file to be interpreted as
  "plain ASCII", select ".t" or ".txt" extensions (see ffaaxxssppooooll source
  for more information).

  After TeX'ing the file with tteexx--bbuuffffeerr (C-c C-b) or tteexx--ffiillee (C-c C-
  f), a small Lisp routine (tteexx--sseenndd--ffaaxx, called by C-c C-x) takes the
  current TeX buffer and picks some items as the sender's name (for
  sseennddffaaxx's "verbose_to"), the fax number (recognized by a line starting
  with FFaaxx--NNrr..::, preferably in the address paragraph starting with
  \\bbeeggiinn{{lleetttteerr}}) and appendices if applicable. If some of the append
  files are unreadable, you are warned in the Emacs minibuffer.  The
  command line for ffaaxxssppooooll is composed and fed into the inferior tex
  shell, being shown in the tex-shell window just like when you do C-c
  C-b.

  To get a nice header page easily, I chose not to set it up in LaTeX.
  Instead, I use a \\ssppeecciiaall command to transparently underlay an
  arbitrary postscript page (for available header and footer space, see
  RREEAADDMMEE..hheeaaddeerrppaaggee).  Thus, you can generate your favourite header page
  with any postscript-capable tool (WinWord, Corel Draw, Photoshop,
  Quark Express, xfig, you name it) without fuzzing around with TeX.
  Thus, the header page layout is decoupled from ffaaxx..ssttyy. Plus, you can
  choose different header pages for different addressees. You could even
  assign certain header pages to specific addressees automagically if
  you were urged to do so. It's just a matter of the file name in the
  PSFILE \\ssppeecciiaall. To use ttssffaaxx, it's advantageous to know something
  about TeX BTW. ;-)

  To preview the page with xxddvvii, you need to have xxddvvii--1188 or later
  because earlier versions cannot handle \\ssppeecciiaall{{PPSSFFIILLEE}} macros. In
  case of doubt, consult the xxddvvii installation instructions. If you
  don't have Display Postscript or NeWS, you need to have xxddvvii properly
  configured to use Ghostscript. Recent xxddvvii versions can be found on
  all CTAN ftp sites, such as ftp.dante.de. Preview is thus be made
  through tteexx--vviieeww (C-c C-v).

  As for printing, I no longer support tteexx--sseenndd--ffaaxx--pprriinntt. The ddvvii22lljj
  filters are very buggy; at least for my Sharp JX-9500 printer, they
  sometimes produce horrible garbage. I prefer converting everything to
  Postscript and piping it through Ghostscript. Thus, this version of
  ttssffaaxx only supports direct printing from the tex-mode, i.e. via tteexx--
  pprriinntt (C-c C-p). Here as well, the appendices aren't printed, only the
  header page.


  That's all. It's fairly simple and in proper lack of superfluous
  features ;-)



  44..  RReemmoottee FFaaxxiinngg


  If you want to send the fax via e-mail to a remote fax server, you
  should use the function tteexx--sseenndd--ffaaxx--mmaaiill (C-c C-m). Apart from the
  different function name, the handling is the same as for tteexx--sseenndd--ffaaxx
  above. The way the fax takes is:


  +o  tex-send-fax-mail (calls ffaaxxmmaaiill as if it would call ffaaxxssppooooll
     locally)
  +o  ffaaxxmmaaiill (produces a MIME message with one attachment per appendix)

  +o  e-mail gateway

  +o  mail2fax.pl (re-creates the original files and calls ffaaxxssppooooll)

  +o  ffaaxxssppooooll

  That is, each file is encoded if appropriate and concatenated together
  with a smart e-mail header. Each fax appendix is represented by a MIME
  attachment. You could view everything with a MIME-compatible mailer.
  Or send a fax directly from Netscape or Z-Mail to the fax server. Have
  a look at ffaaxxmmaaiill if you like. It's straightforward. Since I leave the
  handling and conversion of files to ffaaxxssppooooll (why re-invent the
  wheel?), it's simple too. The bad news is that the file formats you
  can send are restricted to those which are recognized by ffaaxxssppooooll.


  44..11..  SSeettttiinngg uupp tthhee rreemmoottee ffaaxx sseerrvveerr


  You have to set up a "fax" e-mail alias (or whatever you like to name
  it) in your //eettcc//aalliiaasseess, just like,



       fax: |/usr/local/etc/mgetty+sendfax/mail2fax.pl




  Plus, you must maintain the file ffaaxx..aallllooww (as you have to with
  ffaaxxssppooooll). Simply put anyone's e-mail address into the file who should
  be able to fax. ffaaxx..aallllooww must be world readable because mmaaiill22ffaaxx..ppll
  will run as "nobody". "nobody" must certainly be in ffaaxx..aallllooww, too.

  In mmaaiill22ffaaxx..ppll, you should adjust all the directories and paths in the
  first section to reflect your actual setup. Please note that
  mmaaiill22ffaaxx..ppll needs Perl 5 and mmmmeennccooddee from the metamail
  <ffttpp::////ssuunnssiittee..uunncc..eedduu//ppuubb//LLiinnuuxx//ssyysstteemm//MMaaiill//mmaaiillhhaannddlleerrss//> package.

  ffaaxxmmaaiill, its counterpart, needs metamail as well. Be sure to adjust
  the MMAAIILLEERR shell variable at the beginning of the script. ffaaxxmmaaiill must
  be installed on the fax "client" machines! It's best to install the
  entire package on each machine. Only mmaaiill22ffaaxx..ppll needs Perl, so there
  doesn't need Perl to be installed on the clients.

  There's one quirk with ffaaxxssppooooll. The script nowhere defines a PPAATTHH
  variable and thus relies on what it's being given from the calling
  process. sseennddmmaaiill, however, restricts the PPAATTHH given to child
  processes to //bbiinn:://uussrr//bbiinn for security reasons. This is not enough.
  In mmaaiill22ffaaxx..ppll, you should define the variable $$ppaatthh to include all
  necessary directories for the tools called by ffaaxxssppooooll (usually
  /usr/local/bin for the PBMtools and Ghostscript and /usr/TeX/bin for
  ddvviippss). If you don't do this, ffaaxxssppooooll will not be able to process the
  files given on the command line.

  If you are unsure which PPAATTHH to set, send yourself a MIME message with
  attachments. Save it to a file. Then,



       su - nobody
       PATH=/bin:/usr/bin /usr/local/etc/mgetty+sendfax/mail2fax.pl < <file>


  and watch what happens. If ffaaxxssppooooll can process everything fine (check
  with ffaaxxqq when it's done), you're on the safe side. Otherwise watch
  why and where ffaaxxssppooooll fails (a sseett --xx near the beginning helps!)  and
  add the respective directory to the $$ppaatthh string in mmaaiill22ffaaxx..ppll. Easy,
  isn't it?  OK, it could be smarter.


  You have three options for sending faxes via e-mail:



  44..22..  WWiitthhoouutt ttssffaaxx, without ffaaxxmmaaiill


  If you don't use ttssffaaxx nor ffaaxxmmaaiill to send MIME faxes to the fax
  server, be sure to include the following lines in exactly this
  sequence in your e-mail:



       Fax-Res: $RES
       Fax-Dest: $DEST
       Fax-No: $PHONE




  Replace $$RREESS by --nn if you want normal resolution, else leave it empty.
  $$DDEESSTT is the name of the recipient, $$PPHHOONNEE his fax number.

  Sending MIME attached appendices works fine from Netscape. Don't
  forget to convert HTML pages to Postscript before sending them --
  ffaaxxssppooooll has no HTML converter. And yes, you can also read such MIME
  mails with Netscape... So you can CC them to yourself or someone else.

  Your first MIME attachment should be your coverpage. Alternatively,
  you can add a



       Fax-Text:




  header after the FFaaxx--NNoo:: header. Everything from there to the end of
  this part of the MIME message will be used as a coverpage, albeit a
  simple one. This is for people who want to use only Netscape or a MIME
  capable mailer for faxing. See the file sample.mail as an example.



  44..33..  WWiitthhoouutt ttssffaaxx, with ffaaxxmmaaiill


  ffaaxxmmaaiill works just like ffaaxxssppooooll and has some of the same command line
  options. Example:



       /usr/local/etc/mgetty+sendfax/faxmail -a fax@seneca.muc.de \
             -D "Lola" 01234567890 lola.dvi ~/tmp/germany.gif




  If you use ffaaxxmmaaiill, you don't need to care for the lines above. Your
  first file (lloollaa..ddvvii in the above example) becomes the coverpage.



  44..44..  WWiitthh ttssffaaxx


  If you use ttssffaaxx to write and send your faxes, you can handle
  everything from Emacs. The file you write becomes your coverpage as
  usually. In this case, ffaaxxmmaaiill cares in the background for the above
  mentioned lines in your mail message.




  55..  TTOODDOO



  +o  write handy man pages for the tools.

  +o  enhance security for remote faxing (passwords? PGP signatures?)




  66..  IInnssttaallllaattiioonn


  After customizing several paths and UID/GIDs in Makefile, simply call
  mmaakkee iinnssttaallll with super-user privileges, and the files are copied to
  their appropriate directories. Replace "nobody.nobody" by the UID/GID
  pair that your MTA (e.g. sseennddmmaaiill, ssmmaaiill) uses when passing mail files
  to an executable via //eettcc//aalliiaasseess. A short description and manual is
  in tteexx--sseenndd--ffaaxx..eell.  You should adjust the tex-dvi-* commands in tteexx--
  mmooddee--hhooookk..eell and include



       (load "/usr/local/etc/mgetty+sendfax/tex-mode-hook")




  in your ..eemmaaccss. That's it.

  ggeerrtt..tteexx is a sample tex fax source. You can see the \\ssppeecciiaall command
  to underlay the postscript header page, the FFaaxx--NNrr..:: token and the
  %%AAPPPPEENNDD commands to append several files. Watch how I included my
  handwritten subscript ..mmiillzz..eeppss. This one was scanned on a Canon
  CLC-10 with 200 dpi and exported as EPS with the respective Macintosh
  scanning software.  It's that easy... (I didn't include the file here
  for obvious reasons, but you get the idea :-)

  If you try the code, I'd appreciate hints and bug reports. Let's get
  it up and running.

  Have fun!

  Harald Milz (hm@seneca.muc.de <mmaaiillttoo::hhmm@@sseenneeccaa..mmuucc..ddee>)





