Otherware/Otherware_1_SB_Development.iso/amiga/comms/misc/afax125.lzh/AfaxDemo/docs/UserGuide_Beta

Text File | 1992-01-14 | 21.0 KB | 659 lines

========== AmigaFax Release 1.09 ReadMe file ==========

1.09 release  - 13 December 1992

AmigaFax Copyright (C) 1991,1992 by C-Born Software Systems

David Varley
C-Born Software Systems
14 Lunan Avenue
Drumcondra, 3215
Victoria, AUSTRALIA
Ph: [phone]
email: sol.deakin.OZ.AU!drum3!dave

This software is still under development

It is released to selected Beta testers and registered users only.
It may NOT be redistributed without permission.

In return for the use of this software, we ask that you
inform us of problems encountered, and of improvements
you would like to see in the product.

================================================
New since 1.08
--------------

Decoder made more noise-tolerant
User AT commands allow setting of speaker volume, etc
Viewer startup scale config option added
Config options for serial device and unit added
ZyXEL support for high speed UUCP and Fax added (GETTY)
User settable default fonts for header line and normal text in faxes
Copyright notice removed from top line of faxes (Is this wise ??)
Some tidying up of windows and timing

================================================
New since 1.07
--------------

ZyXEL U-1496 modem compatability added.
-> Config file entry DLEmode added, current values allowed are 0 or 1
   Use 1 for ZyXEL Vn 3.9 ROM, don't filter DLE codes from g3 data
   Use 0 for Maestro, DLE filtering on as per latest TR-29.2 revision

FAA program now checks for serial port requests from afaxsend, uucico, etc.
In previous versions you had to use the supplied GETTY to achieve this.

WARNING: Serial locks are currently only supported in the T: directory.
         The UUCP LockDir entry is NOT honored.
         You must set LockDir in uulib:config to T: (default value)
         If your RAM: is faulty, assign T: elsewhere.

================================================
New since 1.05
--------------

Enhanced debugging code added.
Modifications to suit Maestro 3.1 ROM.
Enhancements mode to ViewAFax module.
AFaxSend can take aliases as dialstring.
User configurable page headers for mkafax.
Send/receive status windows, user configurable.

================================================
New since 1.04
--------------

Added ViewAFax module

================================================
New since 1.03
--------------

New modules added :
afaxspl - Fax spooler daemon, many options/features
newfax    - Notifies new fax received, allows print/view/delete, etc
      [Intuitionized interface]
afax    - Intuitionized interface for AFAX create/edit/send etc

Support for user aliases, multiple user groups, via FAXLIB:Aliases
User configuration supported, via FAXLIB:Config

Some changes to paths [executables now in AFAX:C]

================================================
New since 1.02
--------------

Modified installation, AFaxAssign
Selectable serial device and unit support for send and receive
FILL and VERBATIM modes for mkafax
Optional line null-padding on transmit (afaxsend)
Default received fax name length extended (now 4 digits)
Include search path now searches FAXLIB:
Support for Getty (UUCP spooling) added to Faa program.
Immediate Answer added to Faa program
Modified Getty added to the distribution

================================================

INSTALLATION
============

The AmigaFaX software requires certain logical assignments to be made.
See the file AFaxAssign as an example. Put the AFaxAssign into S: and
an entry like this

if exists s:AFaxAssign
    execute s:AFaxAssign
endif

into your S:User-Startup (2.0) or S:Startup-Sequence (1.3)

Current assigns are:

AFAX:        - top level AmigaFax directory
FAXREC:        - default directory for received Fax files
FAXSPOOL:    - directory for outbound AFAX files
FAXLIB:        - directory for AFAX config information
FAXDOC:        - Location for default documents

If you want auto-fax spooling [ie faxes to be sent automatically], you
must add the line
run >nil: <nil: AFAX:C/afaxspl -i n
to your startup sequence. This can be done in AFaxAssign, for example.
The parameter n is a number indication how often you want to try
spooling faxes, in minutes. A typical number could be 30, check every 1/2
hour.

If you want auto-answer with Fax detection, you may either use the modified
Getty command, or use faa directly, by setting
run >nil: <nil: faa
somewhere in your startup sequence.

HARDWARE
--------

Your Amiga <=> Modem cable MUST connect CTS/RTS/DTR/DCD/TXD/RXD/GND
conductors. CTS/RTS are used for flow control handshaking. DTR is used
to keep the modem on line - hangup occurs if it is dropped. DCD is
used for carrier detection.

TXD  2 Transmit Data
RXD  3 Receive Data
RTS  4 Request to Send
CTS  5 Clear to Send
GND  7 Signal Ground
DCD  8 Data Carrier Detect
DTR 20 Data Terminal Ready

ARP
---

If you have the ARP library installed (Libs:arp.library) the system will
make use of it for file requesters.

Support for the ASL library under AmigaDOS2.0 is close, but not in yet.

Printer Setup
-------------

(You may need to experiment)
Using a dot-matrix, Halftone Dithering, Integer Scaling,
Black and White, Density 7 appears to work ok.

================================================

This pre-release Beta package contains nine separate executable programs.

afax    - Intuitionized interface for AFAX create/edit/send etc
newfax    - Notifies new fax received, allows print/view/delete, etc
      [Intuitionized interface]
afaxspl - Fax spooler daemon, many options/features
mkafax     - Convert documents to AmigaFax AFAX IFF file format
afaxprt     - Print and AmigaFax AFAX IFF file using preferences printer
afaxsend - Send an AmigaFax AFAX IFF file to a remote Fax machine
faa     - Receive Fax documents in auto-answer mode
afaxilbm - Convert pages from an AmigaFax AFAX IFF file to ILBM format
viewafax - AFAX file viewer

All modules currently have level 1 debugging enabled.
The command line debug switch is -d, ie -d9 will set level 9 debugging,
and -d0 will set level 0 (debugging off)

AFAX
====

AFAX:c/afax - no command line switches at present.
This brings up a window which you can use to create new Fax documents,
edit the documents, create the actual AFAX files, and send your faxes.
The gadgets available are:

FINE/STD
This gadget allows the user to toggle between Fine (200 DPI) and
Standard (100 DPI) vertical resolution, when creating AFax files.
Standard resolution takes half the space, and half the time to
transmit, of Fine mode, but Fine looks MUCH nicer !!

To:
This is the intended recipient of the Fax. It may be just a phone
number, or it may be an alias. When you enter a string and press
return, if the first character is a digit it will be treated as a
number, otherwise it will be checked for aliases. If no aliases are
found, the string is removed, otherwise the number of aliases found is
shown. [See below for more information on aliases]

From:
This is picked up from the LocalID field in your Config file, if
present. You may override this value. It is a 20 character string sent
to the remote Fax to identify you as the sender, usually your phone
number for return faxes.

Source:
This is the name of the fax source document, usually a .FCOM file,
although plain text or ILBM files may also be used.
If you press return with an empty string, and ARP is installed, a
requester will prompt you for a filename.

AFAX:
This is the name for the actual fax file. The system will usually pick
a name for you, but you may wish to override it.
Note that the AFAX file name will be reserved, but not actually
created, until time to send the Fax. You may force creation with the
"Make" gadget if you wish to test that it is created correctly.
If a document is to be faxed to multiple recipients, only one copy of
the AFAX file will be made. It is automatically deleted when all
recipients have been reached.

Tries:
The number of times to try to get a fax through to a specific
recipient, if problems are encountered, such as remote phone being
engaged. Defaults to three.

Time:
The Fax will not be sent until after this time. An empty field means
send at any time. Fill in as hh:mm, (24 hour format) then press return.
The system will interpret the time, and display the result. Time can
only be in the future, past time is rounded up by a day.

New
Create a new Fax document, and edit it using your configuration editor.
The file pointed to by the configuration entry "Template" will be used
as a fax pro-forma.
The system will pick a default document name for you, you may override
this or keep it.

Edit
Edit a Fax document, using your configuration editor. Note that you
may set both a text and a graphic editor in your config file.

Make
The system attempts to build an AFAX file from your source document.
This is not necessary when sending faxes, but does allow you to check
whether the document will appear as you wish.

View
Invokes the AFAX viewer program "viewafax"

Send
The faxes will be queued for sending to the appropriate recipients.
Note that afaxspl must be running for the faxes to actually be sent.

QCheck
This gadget will bring up the queue check window, to monitor the
progress of outgoing Faxes. From here it is possible to requeue Faxes
that have exceeded their error allowance, and to remove the spool
files for faxes that have been successfully sent, or that are still
queued for transmission.

NEWFAX
======

AFAX:C/newfax faxname
This program is automatically invoked by faa when a fax is received.
It throws up a window informing you of the Fax, with details about it
(name, sender ID, number of pages), and allows you to view, print or
delete it.

AFAXSPL
=======

[run >nil: <nil:] afax:c/afaxspl [-s][-i n]

With the -s (SinglePass) interval option, afaxspl will check for any
faxes witing to be spooled out, and deal with them. In this mode, it
could be launched using cron/dcron/amicron at whatever times you
wished to send faxes.

Without -s it will run and check for faxes to spool at intervals of
every n minutes. You could do this perhaps every 1/2 hour, (n = 30),
or even at 1 minute intervals while testing. The interval will be taken
from the FAXLIB:Config file, if present. The -i option may be used to
override the Configuration interval.

Afaxspl checks for files of the form FAXSPOOL:*.SPL. These are
human-readable. As calls progress, results are added to the end of the
file. If successfully sent, the file is renamed FAXSPOOL:*.OK . If
unsuccessful for more than the specified number of tries, it is
renamed FAXSPOOL:*.ERR . Note that you can re-spool a .ERR file by
using an editor to increase the allowed tries, then renaming it back
to .SPL .

MKAFAX
======

mkafax <docfilename> <AFAX_filename>

mkafax currently recognizes the IFF file types AFAX and ILBM, plain
text files, and AFAX command text files, as input.

A plain text file will be converted to an AFAX file using default settings.

An IFF ILBM will be converted to a single-page FAX document. Only the first
plane is converted, to convert multi-plane (eg DigiView Pics) use another
tool, such as PfiltView (AmigaTeX). May integrate later ?

An AFAX command file uses lines starting with a dot (.) as special
commands, similar to TROFF style text processors. The file MUST start with

 .FCOM
    on the first line to be recognised as a command file.
    .FCOM may optionally be followed by a dialstring or target alias.
    (Currently unused, future compatability)

Other commands currently supported are :

 .PG    Clear out the old page and start a new one
 .LM n    Set the left margin to n characters, in the current font
 .LI n    Set the left  indentation to n pixels (default 50)
 .RI n    Set the right indentation to n pixels (default 50)
 .LJ    Left-justify text and Graphics from now on
 .RJ    Right Justify text and Graphics
 .CT    Center Text and Graphics
 .TS n    Set Tabs every n characters (default 8)
 .PL n    Set page length to n (pixel) rows (default 2292 == A4)
 .FILL    Turn on fill mode
 .NOFILL Turn off fill mode

 .VERBATIM
    All text read in will be printed verbatim, until .ENDVERB

 .VERBINC filename
    Include a file in verbatim mode. Still requires a .ENDVERB

 .ENDVERB
    End verbatim mode

 .FONT name size
    Set the font as specified. Typical use might be
    .FONT topaz 11
    .FONT diamond 20
    .FONT cmr10 30
    and so on.

 .     (dot followed by white-space) Rest of line is a comment

 .INC file
    Include the named file. File may be text, ILBM, or another command
    file. Type is auto-recognised. If a full path is not given to the
    include file, the current directory will be searched, then the
    FAXLIB: directory. Thus addresses, signatures, etc may be kept
    in FAXLIB:

 .DATE    Insert a line with the current date and time, using current font
    and line settings.

(Other commands will be added - suggestions please)

Any line not beginning with a . will be processed as normal text,
according to the current settings.

Fill Mode
---------

In this mode, lines will be filled from input to full width (inside
LR indent) in the current font. Line filling terminates on a dot
command, blank line, or end of page. Left Margin is disabled while
filling.

See the included test.com file for examples of useage.

Changed since 1.01 -
------------------

Alignment (.LJ, .CT, .RJ) and indentation (.LI, .RI) also operate on
ILBM graphics.

ILBM files are now recognized as primary input as well as .INC files.

Works with 1.3. Other bug-fixes.

Changed since 1.02 -
------------------

Added commands .FILL, .NOFILL, .VERBATIM, .VERBINC, .ENDVERB

AFAXSEND
========

afaxsend [-t -d -P] <dialstring> <AFAX_filename>

eg afaxsend 052,786355 MyFaxFile

-D name    - Use name for the device     (default serial.device)
-U num    - Use device unit num         (default 0)
-t     - Use Tone Dialing
-P    - Padding on (default)
-p    - Padding off

Attempts to dial out, connect to the remote fax machine, and tranfer the
specified document.

The dialstring parameter is checked for known aliases. It may be
expanded to multiple destinations if necessary.

After alias expansion, if the first character of dialstring is not a
digit, the whole string will we be sent to the modem non-prefixed as a
dial string. Otherwise normal prefix rules apply.

Padding - Version 2.0 of the Exar ROM does not correctly null-pad
      lines to meet scan-time restrictions for slower Fax machines.
      The AFAX software will add this padding, but it can add to
      the time taken to transfer a Fax. Only some Fax machines require
      the padding, the symptoms are missing scan lines on output.
      Padding can be enabled via 'DoPadding' entry in config. file.

AFAXPRT
=======

afaxprt [-pnum] <AFAX_filename>

eg afaxprt -p2 MyFaxFile

If the -p option is not used, all pages are printed.

Sends the AmigaFax document to the preferences printer. It is a good
idea to set your printer for high density.
Using a dot-matrix, Halftone Dithering, Integer Scaling,
Black and White, Density 7 appears to work ok.

Note that this has not been extensively tested with printers other
than the HPLJIII and the Star NX10.


FAA
===

faa [BaseName]

Fax auto-answer. Sets up the FaxModem to auto-answer and recognise Fax
or data tranmissions. Incoming Faxes will be saved in AFAX format. the
default BaseName is FAXREC:FAX, so that incoming faxes will be named
FAXREC:FAX0000
FAXREC:FAX0001
FAXREC:FAX0002

etc.

Note also that although faa recognises the difference between Fax and
Data, it currently does nothing special with data. I hope to integrate
this with the UUCP system in the future. Any other suggestion ?

To terminate the faa program, send it a CTL_C break. If you ran it
directly from your shell, just type control-C and wait.
If you used RUN or RUNBACK, send a break to its process number.
(eg break 7 all)

Command Line switches are:

-dn    - Set debug on, level n     (default 1)
-D name    - Use name for the device     (default serial.device)
-U num    - Use device unit num         (default 0)
-a    - Immediate Answer
-G    - Run from a Getty

The Immediate Answer switch assumes phone is ringing, configures the
modem & answers immediately. It probably makes sense to attach this to
an alias if you use it this way. eg.
alias fa "faa -a"

The Getty option specifies that faa was run from a Getty. It will not
modify the serial port parameters. It assumes that the Getty has
answered the phone, detected a Fax call, and set up the line
accordingly. Faa will connect, collect a Fax document, and return
control to the Getty.

VIEWAFAX
========

viewafax AFAX_filename

The view initially opens the first page of the Fax document, using by
default a 1:3 horizontal scale to fit one page across the screen.
There are two string gadgets in the title bar. The first allows you to change
the X direction scale, from 1:1 down to 1:8, by typing in the new
value and pressing the return key. The second gadget allows you
directly enter the page number to be displayed. This can also be done
from the command line, using the -p switch, eg

ViewAFax -p 3 myfile

There are also four boolean gadgets in the title bar, |< <- -> >|
which are for first-page, previous-page, next-page and last-page
respectively.

You can scroll around the displayed page using the arrow keys, or the
numeric keypad keys. The window may be resized, but if it is made
larger than the image it will automatically resize if scrolled.

The following keys have specific functions in the display window:

n - go to Next page
b - go Back one page
s - Smaller, shrink the current page (Width)
l - Larger, enlarge the display (Width)
f - got to first page
e - go to end page
q - Quit, exit the viewer

AFAXILBM
========

afaxilbm [-pnum] <AFAX_filename> <ILBM_filename>

eg

afaxilbm -p2 RAM:AFAXR001 FX.ILBM

This will extract the specified page from the AFAX file to the named
ILBM file. It may then be viewed using standard ILBM viewing programs,
such as LoadImage from Fish disks 281 and 355, of programs like
DeluxePaint.

If no page number is given, all pages will be extracted to separate
files, and given names of the format base.1 base.2, etc

The default ILBM file base name is afax_ilbm

==================================================================

FONTS
=====

Some larger fonts have been included in the fonts directory. To use
them, copy them to your FONTS: directory, or under AmigaDOS2.0 extend
the FONTS: assign to include the directory you store them in.

==================================================================

UUCP
====

UUCP integration is underway. If you are using Matt Dillon's UUCP1.13
(or 1.15D), replace your UUCP:c/Getty with the one provided herein.
When running up the Getty, add the option -F to the command line.  Add
the line

fax,*,0,0,(Fax_Connection),ram:,AFAX:C/Faa

to your UULIB:passwd file.

Now a Fax call will be recognised, and the Fax auto-answer program called
to handle it. Normal logins and UUCP connections should function as usual.

A typical getty startup line would be:

run >nil: <nil: Getty -Mh -B2400 -x8 -F AT&C1&D2+FDCC=1,3,0,0,0,0,0,0

for the Maestro 3.1 ROM version.

==================================================================

ADDITIONAL COMPONENTS
=====================

FAXLIB:Aliases
--------------

This file allows you to alias numbers to names, create fax mailing
groups, etc. Aliases may be defined in terms of other aliases.

For example we could have:

joe: 1234596

fred: 9876123

bill: 0981234

customers: joe, fred, bill

Lines beginning with # are treated as comments, a comma means the
alias list continues.

The alias system is modelled closely on the one used in Matt Dillon's
UUCP package. See UUCP documentation for more details.
Thanks, Matt.

FAXLIB:Config
-------------

You can use this file to configure the system to your preferences.

Items covered include:

Editor         - Editor for text, defaults to Edit
Template    - Standard template file for Text Edits
ILBMEditor    - Graphics editor, eg dpaint
DefaultFont    - Default text font
HeaderFont    - Font to use for page headers
PHeader        - Page Header string. Your company name, etc. If not
          present, no page header will be printed.
LeftIndent    - Default indentation for mkafax, pixels
RightIndent    - (Defaults are 50 pixels)
SpoolInterval    - Period at which Queue is scanned for outgoing faxes
RSetup        - User AT command options for receiving
RStatus        - Receive Status Window.
          Line must be present for window to appear.
          LeftEdge, TopEdge are optional
DLEmode (0,1)    - default 0 = Filter input DLEs per TR29 (Maestro)
        - 1 = Don't filter (ZyXEL 3.9)
WSetup        - User AT command options for sending
DialType    - Pulse or Tone
DialPrefix    - Optional, I use ATDP0 to get outside line
DoPadding    - For FaxModems that do not insert nul-padding
          for minimum scan time/line
WStatus        - Write Status Window.
          Line must be present for window to appear.
          LeftEdge, TopEdge are optional
ViewScale    - Default Viewer Scale, 1-8.
          (1 = 1:1, 3 = 1:3, fits page on 640 wide screen)
Debug        - Debug Level
LogFile        - File to send logging information to
LocalID        - 20 character ID to send to remote fax
Device        - Device to use (default is serial.device)
Unit        - Device Unit number (default is 0)

Other items will be added here as required.

This system also is modelled closely on the one used in Matt Dillon's
UUCP package.
Thanks again, Matt.

==================================================================

Thank you for helping to Beta test this software.

Please address any queries to :

David Varley
C-Born Software Systems
14 Lunan Avenue
Drumcondra, 3215
Victoria, AUSTRALIA
Ph: [phone]    ([phone])
Fax:[phone]    ([phone])
email: sol.deakin.OZ.AU!drum3!dave