@DATABASE STFax.guide @$VER: STFax.guide 1.0 (24.12.96) @AUTHOR "Simone Tellini" @(C) "Simone Tellini" @WIDTH 74 @NODE main "STFax User's Manual" STFax User's Manual @{" Introduction " link intro} When, Where, Why, Who, Which :) @{" Disclaimer " link disclaimer} This software is provided "AS-IS"... @{" Copyright " link copyright} Read this! @{" Acknowledgments " link ack} Some boring notes @{" Credits " link credits} My thanks go to... @{" Registering " link register} REALLY IMPORTANT! @{" STFax's Author " link author} How to get in touch with me @{" Bug Reports " link bugs} What to do if... @{" The main window " link mainwindow} @{" STFax's Menus " link menus} @{" Viewer Menus " link viewmenus} @{" ARexx commands " link arexx} @{" History " link history} STFax is ©Copyright 1996-97 by Simone Tellini @ENDNODE @NODE intro "Introduction to STFax" It all began almost an year ago, when for the first time I needed to send a fax... "Well", I said, "I've got a fax modem, I can send it from home...". Unfortunately I had no fax software: the ones provided with the modem were just for MS-Dos and Windows, as usual. So I started looking around for fax programs for my Amiga: there were only two commercial packages, but as I'm almost always out-of-money, I thought it was a good idea to look in the shareware before. I did, but with no luck: I just saw a couple of programs, one worst than the other. Thus, I sat down and began to type... I tried to put in STFax all the functions I thinked I would need, like: - Nice, handy user interface - Phonebook - Scheduler - Reports - ARexx port - Datatypes support for image conversion - On-line help - Printer driver to redirect all print-outs to a fax file and so on... @ENDNODE @NODE disclaimer "Disclaimer" THERE IS NO WARRANTY FOR THE SOFTWARE TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHERE OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY REDISTRIBUTE THE SOFTWARE AS PERMITTED BELOW, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. @ENDNODE @NODE copyright "Copyright And Distribution" STFax © 1996-97 by Simone Tellini Written by: Simone Tellini Piazza Resistenza 2 42016 Guastalla RE ITALY reqtools.library is © copyright 1992-1994 Nico François 1995 Magnus Holmgren STFax is (C) 96 by Simone Tellini. This program is SHAREWARE: if you use it, you should @{"send me" link author} your registration fee; in that way you will become a registered user, you'll receive the keyfile for the program and will be able to use STFax without any limitations. Supporting shareware is very important, you like good programs at a very low price, don't you? ;-) This program may be freely distributed provided that all files are included in the distribution without any modifications. You may @{b}NOT@{ub} charge more than Fred Fish does for a single library disk. This program may @{b}not@{ub} be uploaded on BBS's that claim copyrights on the uploaded material. The key file for STFax is strictly personal and is @{b}NOT@{ub} distributable in any way, only a backup copy for the registered user is allowed. Commercial distribution of STFax and/or its relative files is @{b}NOT@{ub} allowed without written permission from the author. This also means the distribution on cover disks, disk magazines etc. I'll be glad to give the permission to insert this program on disk magazines or cover disks @{I}if@{UI} I receive a copy of it. Write @{"me" link author} for details. @ENDNODE @NODE ack "Acknowledgements" The class 2 documentation I've used to create STFax was: SUPRA TECHNICAL SUPPORT BULLETIN CLASS 2 FAX COMMANDS FOR SUPRA FAXMODEMS 6/19/92 Very interesting was also the "QUICK TUTORIAL ON FAX COMMANDS AND ODDITIES" in the BGFax manual. Some code of STFax derived from other programs' sources. These copyrights apply: /* 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. */ --- /* gdevdfax.c * DigiBoard, Inc. DigiFAX driver for Ghostscript. * * 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. */ @ENDNODE @NODE credits "Credits" My thanks go to: - Mario Branchi Gian Maria Calzolari Luca Danelon Andrea Trevisan for beta testing & suggestions - Michael van Elst for his help on the printer part - the authors of the icons used: they were all taken from PD sources - all those who will register :^) @ENDNODE @NODE register "How to register STFax" I've put a big effort in making STFax: more than two years of development. So I think it's quite fair to ask you to pay something in order to be able to fully use it. Once you register, you'll get a special and @{B}personal@{UB} key file which will let you use STFax without any restriction. Minor upgrades are free. I may charge you a @{I}small@{UI} fee for major upgrades. To register, you need to @{"fill the order form" system "Ed OrderForm.txt"} and send @{"me" link author} it along with your registration fee, that is @{b}35 US $@{ub}. Accepted methods of payment are cash, international postal money order or EuroCheques. Any other form of payment will @{b}NOT@{ub} be accepted. Please note that unwanted cheques are destroyed, not returned. If you have an Internet account, you can receive your key in a PGP encrypted message: just send to @{"my email address" link author} your PGP public key. The key file will be shipped @{B}only@{UB} via encrypted mail. NOTE FOR @{B}ITALIAN@{UB} USERS: Per gli utenti italiani, la quota di registrazione è di LIT. 45.000. I metodi di pagamento accettati sono contanti, vaglia o assegni. @ENDNODE @NODE author "STFax's Author" Send comments, donations, gifts and your registration fees to: Simone Tellini Piazza Resistenza 2 42016 Guastalla RE ITALY You can reach me also via electronic mail: Internet: wiz@pragmanet.it Fidonet: 2:332/502.18 (Simone Tellini) I've also got a WWW page: http://www.pragmanet.it/~tellini/main.html @ENDNODE @NODE bugs "Bug Reports" STFax is a completely new program and this is the first release, so it would be quite normal if some bugs will show up. I hope they won't, but anyway... ;) If you discover a bug, be it little or huge, please @{"send me" link author} an E-Mail. Don't think that I know it already, send a message. Try to be specific and describe me how to reproduce the bug (whenever it's possible). When you send me your bug report, please include the file STFax:STFax.log, created setting the @{"log level" link miscprefs} to DEBUG. Don't send in a log of 2 gigabytes, just send the log of the session in which the bug showed up, ok? ;) @ENDNODE @NODE mainwindow "The main window" The main window of STFax will look like this: @{U} @{UU} @{" " link prtdriver} Printer Driver @{" Edit Fax " link edit}@{" View Fax " link view} @{" Transmit " link send}@{" Receive " link recv} @{" Scheduler " link scheduler}@{" View Reports " link reports} @ENDNODE @NODE prtdriver "STFax Printer Driver" Using this gadget you can activate/deactivate the printer driver of STFax. This is a special driver that converts into a fax file what is sent to the printer. Thus you can converts into a fax any document created with a program that let you print it, e.g. WordProcessors, Spreadsheets... So far, the driver is not guaranteed to work with all the programs: if you have some troubles with it, please report it to @{"me" link author}, specifying which program have you tried it with and which are the results. @ENDNODE @NODE edit "Edit a fax" When editing a fax, a window will appear with these gadgets in it: Pages In these listview you can see the pages of the fax. Selecting a page, the following four  gadgets  will be enabled. View @{"View" link view} the selected page. Delete Remove the selected page. Move Up Move the selected page up or  down.  These  gadgets Move Down will let  you  rearrange  the  page  order  of  the document  you're   editing.  To  make  the  changes permanent you need to @{"save" link save} the fax. From image... This will open a file requester to select a picture file. Then the image will be converted in  the  fax format and a new  page  will  be  appended  to  the document. STFax can convert any kind  of  image  into  a  fax, provided that you have the right datatype installed. If you can't use datatypes, you  can  convert  only IFF-ILBM images. From text... This will open a file requester to select a text  to convert into a fax. See  @{"Fax  preferences" faxprefs}  for  the options you can set for the conversion. STFax  also  supports  ANSI  sequences,  like  bold, underline, italic... Edit If you want to enter the text for the fax in a quick way, this gadget is for you. It will open the editor configured in the @{"Misc preferences" link miscprefs}  requester  and convert into a fax what you write. You can abort the  conversion  quitting  the  editor without saving the text. @ENDNODE @NODE view "View" This will open the viewer window. From here you can print the fax or save it as an IFF-ILBM picture. See the @{"Viewer Menus" link viewmenus} for more info. @ENDNODE @NODE send "Transmit" This will open a small requester with these gadgets inside it: Send to Insert here the number to which send the fax. You can use the 'R' gadget next to this one to open a requester with the phone numbers  stored in your @{"phonebook" link phonebook}. Then, you can select one or more of them: if you select more than 1 number, the gadget "Send to" will  appear  ghosted  and the fax will be sent to each of those numbers. Make Cover Selecting this gadget, a  cover  page  will  be sent before your fax. Send Now This tells STFax to send immediately the fax. Schedule This lets  you  add  the  current  fax  to  the scheduling queue. To schedule a fax,  it  needs to be saved on disk: if it has not  been  saved yet, STFax will save it in the  @{"Out  dir" link miscprefs}  with the  name "Fax_X.stf",   with  a  progressive number instead of the 'X'. Cancel Abort the operation. @ENDNODE @NODE recv "Receive" This tells the modem to answer to an incoming call. You can use it when the @{"autoanswer" link miscprefs} is switched off or if you want to receive a document while already on line: e.g. if you were speaking on the phone with someone and you need to receive a fax from him. The incoming fax is stored in the directory you setup as Fax In directory in the @{"Misc prefs" link misc prefs"} requester. The fax will be called "Fax_X.stf", with a progressive number instead of the 'X'. @ENDNODE @NODE scheduler "Scheduler" Using the scheduler you can program STFax to send a fax at a specific hour. The scheduler window contains a listview in which you can see the active scheduling queue: double-clicking on a item, you can edit it. The other gadgets are: Add This will open a small requester with which you can set which fax to send and at what time and  day  it will be sent. Remove This will remove a scheduled event from the queue. Change time This will let you edit a scheduled event. @ENDNODE @NODE reports "View Reports" Here you can view all the faxes that you have sent or received or that are in the scheduling queue and also those that couldn't been sent. At the top of the window there's a cycle gadget: use it to cycle through the various lists: @{"Sent" link send}, @{"Received" link recv}, @{"Scheduled" link scheduler} and Failed. In the listview you can see some data regarding the faxes: date and time of transmission, duration of the transmit session, number of the remote modem and name of the fax file. Double-clicking on a fax you can view it. If the selected list is "Scheduled", with a double-click you can edit the @{"scheduled fax" link scheduler} data. At the bottom of the window, there are these gadgets: Remove This will remove the selected item from the list. Resend This can be used if you want  to  send  again  the selected fax. See the @{"Send" link send} chapter for more info. Print This will print the list you're looking at. Free List This will empty the selected list. @ENDNODE @NODE menus "The menus of STFax" These are the menus of STFax: Project @{" About... " link about} @{" New " link new} @{" Open... " link open} @{" Save " link save} @{" Save as... " link saveas} @{" Iconify " link iconify} @{" Quit " link quit} Fax @{" Edit... " link edit} @{" Transmit... " link send} @{" Receive... " link recv} @{" View Reports... " link reports} @{" Scheduler... " link scheduler} Preferences @{" Fax... " link faxprefs} @{" Modem... " link modemprefs} @{" Strings... " link stringsprefs} @{" Misc... " link miscprefs} Viewer Screen @{" Use main screen " link viewermainscr} @{" Change... " link viewerchangescr} @{" External programs..." link extprgs} @{" Timeouts... " link timeouts} @{" Phonebook... " link phonebook} @{" Save " link saveprefs} @ENDNODE @REMARK *** Project *** @NODE about "Project/About..." Try it... :-) @ENDNODE @NODE new "Project/New..." This will free the fax in memory (if there's one). If the fax has not been saved yet, you will be asked if you want to save it or continue without saving. @ENDNODE @NODE open "Project/Open..." This will open a file requester to select a fax file to load. @ENDNODE @NODE save "Project/Save..." This will save the current fax. If the fax has not been saved before, you will have to enter the name of the file. @ENDNODE @NODE saveas "Project/Save as..." Save the current fax in the file you select via the file requester. @ENDNODE @NODE iconify "Project/Iconify" Iconifies STFax. When iconified, STFax will still handle incoming calls, the scheduler queue and the ARexx commands. @ENDNODE @NODE quit "Project/Quit" Quit STFax. If the current fax has not been saved, you will be asked what to do: if save & quit, quit without saving or cancel the action. @ENDNODE @REMARK *** Preferences *** @NODE faxprefs "Preferences/Fax..." You can set several things regarding your faxes aspect. In the fax preferences requester you will find these gadgets: Company Insert your name or company. This will be  used  in the fax cover. Fax # Insert here your fax number. This number is the  ID of your machine. You can enter anything  you  want, but please remember that  not  all  characters  are allowed, according to  the  fax  standard.  Allowed characters are digits 0-9, + and the space. Examples: +39 522 123456 OK +39-522-123456 Not defined HELLO WORLD Not defined You should never have troubles even with no defined sequences, but if a fax machine misteriously  hangs up to your calls, check that this number is ok. Phone # Insert here your phone number. LetterHead Here you can insert the name of an image  or  ASCII file that STFax will put in the top of every page. Signature Same as LetterHead, but this will  be  put  at  the bottom of every page. Text Font The font to be used when  converting  ASCII  files into a fax. I suggest you  to  use  a  quite  large font. Margins Left These are the margins used to layout the text while Right converting it. They are expressed in characters. Paginate If selected STFax will create a new page every  tot lines, depending of  what  you've  entered  in  the following gadget. Otherwise, STFax  will  create  a single page. Please note that if create a very long page, probably you won't be able to view it due  to lack of memory. Lines Number of lines per page. @ENDNODE @NODE modemprefs "Preferences/Modem..." In this requester you can set all the parameters regarding the modem handling. Device Serial device to use. Unit Unit of the serial  device.  If  you  don't  own  a multiport card, this will probably be 0. Baud Speed of the serial port. The default value (19200) should be ok for most people. If you want to  change it, please check the manual of your modem: in  fact, you cannot enter any value  you  wish,  but  only  a baud rate supported by your modem. If  you  enter  a wrong value, you should see the message "Modem  not responding" when clicking on the "Ok"  gadget.  Then you'll have to switch your modem off, then on again, change the baud rate with a  good  value  and  click again on the "Ok" gadget. Rings Number of rings to wait for before answering. Shared If selected, the  serial  port  will  be  opened  in shared mode. Use this gadget if you  need  to  share the  serial  port  among   more  than  one  program, for example, between STFax and a mailer. Retry Minimum number of  attempts  STFax  should  do  when sending a fax. Redial Delay Delay between two attempts. Init Init string for your modem. Dial Mode This tells STFax if it should call in tone or  pulse mode. If you can, you'd better use tone mode. @ENDNODE @NODE stringsprefs "Preferences/Strings..." In this requester you can set the strings that are used by your modem to communicate the events to the program. You should change these strings @{b}only@{ub} in the case that you own a very exotic modem. @ENDNODE @NODE miscprefs "Preferences/Misc..." Auto Answer If checked, STFax will automatically answer the phone when it detects an incoming call. STFax will wait until the number of rings set in  the @{"modem" link modemprefs} preferences requester are detected. Quiet Modem Selecting   this,  STFax  will  set  the  modem speaker off. Make Icons If checked, STFax will create an icon  for the faxes it saves. Close = Iconify If checked, the close gadget of STFax's  main window will cause STFax to  be  iconified,  not quitted. Mode You have two options: FAX/DATA or ONLY FAX. In  the   first  mode,  STFax  will  spawn  the external program set in the @{"External programs" link extprgs} requester when a data call is detected. Instead, in the ONLY FAX mode, STFax will  send out the text saved in the file STFax:NoData.txt when a data call is detected and then  it  will hang up. If the file doesn't  exists,  it  will only hang up. Log Here you can set the logging level. Higher  the level is, more the informations put in  the log file (STFax:STFax.log) are. @{b}NOTE:@{ub} "Debug" level is the highest and  if  you have troubles with STFax, you  should  send  me the log produced with  this  level  along  with your bug report. Editor This is the  command  line  used  by  STFax  to invoke the editor when needed. "%s" is replaced by the name (and the path) of the file to edit. @{b}NOTE:@{ub} the editor should not detache itself from the parent process! So,  if  you  use  such  an editor (like  CygnusEd),  you  should  put  the right parameter in the command line to  prevent it from detaching itself. For example,  if  you use CygnusEd, you should  use  a  command  line like: Ced %s -keepio Or if you use GoldEd: Ed %s STICKY Fax In Directory  in   which   STFax  will  store  the received fax. Fax Out Directory   in   which  STFax  will  store  the outgoing faxes. @ENDNODE @NODE viewermainscr "Preferences/Viewer Screen/Use main screen..." If this item is set, the faxes will be displayed on the same screen of STFax main window. @ENDNODE @NODE viewerchangescr "Preferences/Viewer Screen/Change..." This lets you select a new screen on which STFax should display the faxes. A good resolution is the PAL Super Hi-Res Lace with 2 colors (the faxes are in black and white, so more colors are useless). @ENDNODE @NODE extprgs "Preferences/External Programs..." Here you can set the external programs that STFax will spawn when a data or voice call is detected. To be able to use these feature, you should set both STFax and the external program to open the serial device in @{"shared mode" link modemprefs}. You can use these symbols in the command line: %d Serial device to use %u Device unit %b Baud rate of the serial port %f Flags of the serial port @ENDNODE @NODE timeouts "Preferences/Timeouts..." With this requester you canconfigure the timeouts that STFax uses in the modem handling. The default values should be fine to you, anyway if your modem behaves differently, you can change them. Above all, the Connect and Answer timeouts are the most subjected to changes. @ENDNODE @NODE phonebook "Preferences/Phonebook..." A fax program without a phonebook is not very comfortable, at least in my opinion, so here it is. :-) Phonebook Entries In this listview you can see the numbers stored in your phonebook. Double-clicking on one item, you can edit it (see below for a description of the edit requester). You can select more  than  one  item  at  once, clicking on the item you want to  select  while pressing the SHIFT key. New Adds a new item to the phonebook. Delete Remove the selected entries from the list. Select All Select all the items. Deselect All Deselect all the items. Edit Edit the selected items. You can achieve the same result by double clicking on one item. Sort Sort the entries in alphabetic order. Load Load a new phonebook into memory. If you  @{"save" link saveprefs} the prefs, that phonebook will be  used  by default. Save Save the phonebook. When editing an entries, a requester with these gadgets will appear: Name Name of the person/company. Number Fax number. Note Anything you want. Make Cover If checked, when you @{"send" link send} a fax to that person the "Make Cover" function will be automatically activated. ATTN Person to whom the fax should be addressed. LetterHead If this is not checked, the global preference set in the @{"Fax prefs" link faxprefs} requester will be used. If checked, the file you specify here  will  be used when sending faxes to this person. You can leave  the   gadget   empty   not  to  use  any letterhead. Signature Same function as LetterHead. @ENDNODE @NODE saveprefs "Preferences/Save" Save the current configuration to the prefs file (STFax:STFax.prefs). The position of the main window is saved too, so you can place it where you like it most on your desktop, without having to move it every time. @ENDNODE @NODE viewmenus "Menus of the viewer" Fax @{" Save IFF... " link saveiff} @{" Print... " link print} @{" Close " link closeviewer} View @{" Invert " link invert} @{" Flip Vertically " link flipvert} @{" Flip Horizontally " link fliphoriz} @{" Next page " link nextpage} @{" Previous page " link prevpage} @{"Scale" link scale} 1:1 1:2 1:4 @ENDNODE @REMARK *** Fax *** @NODE saveiff "Fax/Save IFF..." This will open a file requester to select where to save the fax. Then the current page will be saved as IFF-ILBM picture. @ENDNODE @NODE print "Fax/Print..." This will print the current page. @ENDNODE @NODE closeviewer "Fax/Close" This will close the viewer. @ENDNODE @REMARK *** View *** @NODE invert "View/Invert" This will invert the colors of the fax. @ENDNODE @NODE flipvert "View/Flip vertically" This will flip the fax vertically. It's useful if you received the fax upside-down. @ENDNODE @NODE fliphoriz "View/Flip horizontally" This will flip the fax horizontally. @ENDNODE @NODE nextpage "View/Next page" This will show the next page, if it exists. @ENDNODE @NODE prevpage "View/Previous page" This will show the previous page. @ENDNODE @NODE scale "Scale" In this menu you can select the scale to use to view the fax. @ENDNODE @REMARK *** ARexx *** @NODE arexx "STFax ARexx commands" STFax has got an ARexx interface. These are the commands available in the current version: @{" OPEN " link rxopen} @{" QUIT " link rxquit} @{" SAVE " link rxsave} @{" SAVEAS " link rxsaveas} @{" SEND " link rxsend} @{" VIEW " link rxview} @ENDNODE @NODE rxopen "OPEN" TEMPLATE OPEN FILE/A FUNCTION OPEN will load the specified fax into STFax. INPUTS FILE/A name of the file to load RETURNS 0 no errors 20 the fax couldn't be open @ENDNODE @NODE rxquit "QUIT" TEMPLATE QUIT FUNCTION Make STFax quit. If the current fax has not been saved yet, the user will be asked to confirm the action. @ENDNODE @NODE rxsave "SAVE" TEMPLATE SAVE FUNCTION Will save the current fax. If the fax has not been saved yet, a file requester will pop up to  choose  the name of the file. @ENDNODE @NODE rxsaveas "SAVEAS" TEMPLATE SAVEAS FILE FUNCTION Save the fax. INPUTS FILE name of the file to save the fax in. If  it  is not specified, a requester will pop up. @ENDNODE @NODE rxsend "SEND" TEMPLATE SEND NUMBER/A FUNCTION Sends the current fax to the  specified number.  Note that this command won't have any effect if there's  no fax in memory. INPUTS NUMBER/A number to send the fax to. RESULT 0 if the fax was sent succesfully 10 if the transmission failed @ENDNODE @NODE rxview "VIEW" TEMPLATE VIEW PAGE/N FUNCTION View the current fax. This command won't  have any result if there's no fax in memory. INPUTS PAGE/N Number of the page to show. The default  is the first page. RESULT 0 no errors 10 if the page number was greater than the number of the pages of the fax. @ENDNODE @REMARK *** History *** @NODE history "STFax History" STFax History ------------- 1.79 01/01/97 First public release. @ENDNODE