.so User:msh/doc/an .TH "Fax" 1 "El Cheapo" "Olaf 'Rhialto' Seibert" "V24.05.93" .SH SYNOPSIS .nf ."savetabs off Usage: iff2fax [-o fax-file (ilbm.g3)] [-r raw faxfile] [-a (append)] [-sN skip N BODYs] [-x/y x/y-offset (50)] [-v] [-i (invert)] iff-files Usage: asc2fax [-o fax-file (ascii.g3)] [-r raw faxfile] [-a (append)] [-x/y x/y-offset (50)] [-v] [-i (invert)] [-f name.font] [-s fontsize] ascii-files Usage: append [-o fax-file] fax-files Usage: fax2iff [-o iff-file (fax.iff)] [-v] [-i (invert)] fax-files Usage: faxsend phone [files..] Usage: faxrecv -d queuedir/ -f faxdevice -l loglevel -v -i .fi .SH OVERVIEW El Cheapo Fax is a very cheap and simple package to send and receive faxes using your Amiga and a suitable (Class 2) Fax modem. It is not particulary user-friendly, nor is it blazingly fast. It just does everything I need. In fact, as you and I don't need facsimile at all, it does a lot more. The basic way of using El Cheapo Fax is that you first create a fax data file from text or IFF ILBM source files, and later send this file to the receiving fax. Each fax page will be in a separate file. In the other direction, you receive a fax file first, and afterwards you can convert it to a viewable IFF ILBM file. The necessary software has partly been scraped together from various sources. See the section on copyright for full details. All original code is @X(169) Copyright 1993 by Olaf Seibert, and All Rights are Reserved. The GNU General Public License applies to this software. The text of the GPL can be found in the file COPYING. .SH REQUIREMENTS - A Class 2 fax modem. .br - A 7 to 10 wire cable that connects TXD (2), RXD (3), RTS (4), CTS (5), DSR (6), GND (7) and DTR (20) and optionally Shield GND (1), DCD (8) and RI (22). .br - Large fonts. Suggested are 30+ high pixels for fixed-width fonts, 50+ for proportional fonts. .br - An IFF ILBM file viewer. Currently, .I faxsend relies on RTS/CTS handshaking between the modem and the computer. It seems that this is not standard, but is at least supported by the Supra V32bis FAX modem, ROM version 1.200H. .SH LIMITATIONS Currently, no parameters can be chosen. Everything is fixed as 1728 pixels wide (in 215 mm), vertical resolution is fine (7.7 lines/mm), compression is 1-D Huffmann, no error correction mode, no binary file transfer. This, however, is purely a software matter, and thus fixable. .SH USAGE It is probably easiest to start at the Rexx script that glues together the functionality of the other programs. Basically you write a text file interspersed with simple formatting parameter sets. Every block of text between parameters is processed to fax data. No text-fitting is currently done; you must make sure yourself that everything fits on the paper. You must have specific provisions for directing output for each page to a separate fax file. Several options apply to more than one of the subprograms. It is therefore best to discuss them now. Generally, all options must be given before the input files. .ul "-o fax-file You must always select an output file. .ul "-a Append to output file, instead of overwriting it. Set by all2fax for all fileparts but the first. .ul "-x/y x/y-offset Normally, all fax data is offset by 50 pixels both horizontally and vertically. The x offset is needed to prevent any data to fall off the left edge of the paper. The y offset is only needed for the first part of a fax page, if at all. Therefore, .I all2fax resets the -y option to 0 for every part after the first. .ul "-v Verbose. Some subprograms support this, some don't. .ul "-i Invert pixels before conversion. Probably only useful for converting ILBM images. .ul "-r Raw. Don't append an end-of-page marker to the output. This option is set initially, but reset for the very last part (this is detected by the end of file condition when reading its text). The commands supported by all2fax are: .ul "@.args Process the preceeding file part by running it though asc2iff, and set the given arguments (in addition to those given earlier) for the next part. Most options will be left untouched and remain in effect for succeeding parts (exceptions are -a, -r, -y). Binary options (switches) can be reset with a double dash (as in --a). .ul "@.doit Set the given arguments, just as .args would, and process the preceeding file part with asc2iff. .ul "@.iff Process the given arguments, and run iff2fax with the relevant parameters. .ul "@.raw Run append with the relevant parameters plus those given here. Note that these are not processed in the usual fashion - these arguments are purely one-shot. Append is used to append a previously created (raw) fax file to the output. This is useful for including output of FaxPrinter. .ul "@.rexx Execute the given rexx command. .ul "@.shell Execute the given shell command. Now on to the information specific to the several subprograms. .ul "asc2fax .ul "-f any.font -s size Select the font and size to be used. Remember that because of the resolution of a fax, you need quite large fonts. Suggested mininum sizes are 30+ pixels for fixed-with fonts, 50+ for proportional fonts. These will allow approximately 80 characters of text per line. .ul "iff2fax Iff2fax is for including ILBMs verbatim (or inverted). No scaling of any kind is done. To get scaled (and possibly dithered) pictures of appropriate size it is probably best to use the FaxPrinter. This program would actually be more accurately named "ilbm2fax", but perhaps more general iff support will be provided in the future (though I doubt it). But in any case, iff2fax delves into complex IFF files and converts all FORM ILBMs that it finds, each on a separate page, respecting the -x/-y offsets. Because faxsend doesn't support multiple-page fax files yet, you .ul "must use -r to suppress the page terminators in the case of IFFs with multiple ILBMs. This simply glues all pages underneath each other. .ul "FaxPrinter This is not a stand-alone program, but is a standard Preferences printer driver instead. This enables you to create fax graphics from your favourite graphics or printing program (for example, DeluxePaint, ADPro, Post, Ghostscript). Colour graphics can be dithered this way, but please note that the fax data "compression" algorithm behaves very badly on dithered graphics (a single white or black pixel is encoded in a 6 or 3 bit sequence, respectively). You are advised to use black & white graphics whenever possible, unless you don't mind an enormous phone bill. FaxPrinter is the only part of El Cheapo Fax that can generate low-density (i.e. non-fine) fax data. Therefore you should select a printer density of 4 or higher. The -r(aw) switch is implemented by the "SPECIAL_NOFORMFEED" printer flag. Your printing program should enable you to set this, usually with an option like "no formfeed" or "don't eject paper". Support for text output is completely absent from FaxPrinter. You can use a wordprocessor that prints text as grapics, or asc2fax. .SH VIEWING You can view a fax file by converting it to an IFF ILBM file (using fax2iff) and viewing it with your favourite picture viewer. It is recommended that it is capable of displaying very large pictures, and that you select a high resolution display mode (at least hires interlace). Mostra performs great for this. Fax2iff can optionally invert the fax for you (-i), if your viewer program uses black as background and white as foreground color. A PAL hires/interlace display mode has approximately the same aspect ratio as a fine mode fax. My monitor displays approximately 2.4 pixels/mm horizontally and 2.66 pixels/mm vertically, while a fine fax is 8 pixels/mm horizontally and 7.7 pixels/mm vertically. A fax will thus appear a bit too wide. An NTSC mode would be 2.4/2.01 and make the fax a bit too tall. In both cases, the fax will be over 3 times enlarged on screen. .SH SENDING You send a prepared series of fax files with faxsend. The parameters are simply the phone number to be called and the names of the files to send. Remember, only one page per file. The phone number is given as a Hayes modem style dial string. It is simply appended to an ATDT command. Valid dial characters are: .nf 0-9 Numeric Digits * # A-D Auxiliary Digits T Tone Dialing P Pulse Dialing , Pause for (S8) seconds, default is 2 seconds / Pause 1/8 second in dialing sequence W Wait for second Dial Tone .fi The -l option allows you to select the verboseness of progress reporting. Values are from 1 to 8, 8 being most verbose. Default logging level is 5, which reports warnings and all more serious messages. The serial device to be used for the faxmodem can be specified with -f unit/nameof.device. Default is -f 0/serial.device. Both parts of the string can be omitted. .SH RECEIVING (currently untested!) To receive faxes, you should start faxrecv. When it detects any input from the modem (presumably a RING message) it will attempt to answer the call in fax mode. There is no need (and in fact, you should not) set your modem to autoanswer mode. Incoming faxes are written into subdirectories of a spool directory (-d option), with each page in a separate file, plus a LOG file containing session information. The given directory must end in a : or /. To immediately answer the phone (if it is already ringing) specify the -i option. In this case, faxrecv answers the phone immediately after initialisation. If you insist on auto-answer, and have some front-door program that can detect fax calls, double the -i option. In this case, the modem is not initialised, the phone not answered (because it already has been), and fax commands are issued immediately. This is experimental. .SH COPYRIGHTS Significant parts of this package have been lifted from other packages. The following copyrights apply: For tofax.c (derived from Ghostscript 2.2's file gdevdfax.c): .nf;.in 0 /* * Copyright 1992 DigiBoard, Inc. All rights reserved * * Permission to use, copy, modify, and distribute this software and its * documentation for any purpose and without fee is hereby granted. * This software is provided "as is" without express or implied warranty. */ /* gdevdfax.c */ /* DigiBoard, Inc. DigiFAX driver for Ghostscript. */ and /************************************************************************* The rest of this file is a FAX encoding algorithm derived from pbmplus. It is not the normal DigiFAX algorithm. The following copyright applies. ** ** Copyright (C) 1989 by Paul Haeberli . ** ** Permission to use, copy, modify, and distribute this software and its ** documentation for any purpose and without fee is hereby granted, provided ** that the above copyright notice appear in all copies and that both that ** copyright notice and this permission notice appear in supporting ** documentation. This software is provided "as is" without express or ** implied warranty. *************************************************************************/ .fi;.in @ni For fromfax.c (derived from pbmplus' file g3topbm.c): .nf;.in 0 /* g3topbm.c - read a Group 3 FAX file and produce a portable bitmap ** ** Copyright (C) 1989 by Paul Haeberli . ** ** Permission to use, copy, modify, and distribute this software and its ** documentation for any purpose and without fee is hereby granted, provided ** that the above copyright notice appear in all copies and that both that ** copyright notice and this permission notice appear in supporting ** documentation. This software is provided "as is" without express or ** implied warranty. */ .fi;.in @ni For the printer driver, part of the code is a stripped-down version of Commodore's example printer driver for the HP Laserjet.