rtsi.com

home *** CD-ROM | disk | FTP | other *** search

/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / TELECOM / GNU_ATP_1_40.lzh / DOCS / atp.doc next >

Wrap

Text File | 1993-09-12 | 38KB | 818 lines

ATP(1) ATP(1) NAME atp - a program for reading/archiving QWK format mail packets SYNOPSIS atp [ bbsname | bbsname.qwX ] where bbsname is the name of the QWK packet with extension omitted OR the long form "bbsname.qwX" where `X' is any valid filename character, typically the letter `k' or a digit in the range 0-9. DESCRIPTION ATP is used for reading and replying to messages contained in QWK mail packets which are available through public access bulletin boards. It is based on the framework set forth by Rene Cougnenc with his experimental reader `Azer- TyuioP' (sometimes referred to as Azerty). The name `AzerTyuioP' is merely a list of the top row of keys of a continental French language keyboard. ATP took its name from the capitalized letters in that tagline. However, most of ATP is original, and in this regard it is a ful- fillment of Rene Cougnenc's code rather than a direct port. Although Cougnenc never intended for AzerTyuioP to be a complete reader, ATP attempts to supply the missing parts and make it a useful daily tool. Please note that like its predecessor, ATP uses a a bi-lingual framework and that ATP may be compiled for French language use also. With release 1.4, ATP now includes the Rich Salz & Simmule Turner emacs-style command line editor with command his- tory. Note that this is covered by a separate copyright. Upon starting ATP, you will be presented with a command prompt. This prompt will show the current active BBS and the conference. At any time you may type `help' at the command prompt to receive a summary of commands. ATP also functions as a mini-shell allowing you to enter many com- mon UNIX commands at the prompt. A BBS will typically carry topical news conferences. By using an offline mail reader such as ATP, one may dial up a BBS, start a program known as a mail door, and quickly gather the current news for reading and replying to offline by use of a mail reader. There are several formats for offline mail packets but QWK is the most common. Some of the more popular QWK mail doors which produce these packets are Qmail, Markmail, Jimmer, and TQM. ATP can han- dle QWK packets produced by any of these doors so there is no need to worry which one to use. FEATURES In addition to reading and replying to mail, ATP maintains archives of past messages. These can be reviewed at any time. As new QWK packets are loaded, they are immediately added to the archives. Pointers to the last read messages are maintained. Loading a new mail packet will not reset these pointers. Reading will resume with the last read message in each conference. By entering a number at the command line, the pointer will be reset to that message number. In this way you can move backward and forward among the messages at will. ATP will support 8192 conferences per BBS and message size of up to 150,000 bytes. This is roughly 3000 typical lines of message text. Note that these limits are somewhat arti- ficial, and are easily changed should the need arise. The 8192 conferences per board is a limit set for backward compatibility with some older mail doors. Your tagline file can hold many thousands of taglines, essentially no limit for most purposes. Taglines are stored in a plain text file. Other features include the ability to scan message head- ers, a tagline management system, support for FIDO or reg- ular style taglines, personal mail notification and per- sonal mail conference, the ability to search messages for strings, a separate conference for replies, kill and change security on replies, tagline selection by random, automatic, or direct means, hooks for a spelling checker, powerful command line editing with history recall. COPYING AND NO WARRANTY ATP is copyrighted free software provided WITHOUT warranty of any kind, NOT EVEN the implied warranty of mer- chantablilty or fitness for any particular purpose. Use at your own risk. ATP may be used in any way you wish so long as you comply with the provisions of the Free Soft- ware Foundation GNU General Public License. Essentially this means that you must provide this source code along with any code which you have derived when you pass on binaries. You can not withhold the rights which you your- self have been granted. Please type `show terms' from ATP's command line for a display of warranty disclaimer and pointers to pertinent documents. This software should have come with a copy of the GNU General Public License. You may obtain a copy of this license by writing to: Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. ENVIRONMENT ATP looks for certain environment variables: SHELL, HOME, and ATP. The SHELL environment variable must properly reflect the path to your shell. The HOME environment vari- able reflects your home directory path. Normally your command processor shell will automatically set the SHELL and HOME variables for you. The ATP environment variable is optional. You may set this to a directory path differ- ent than your home directory if you wish, and ATP will set up shop there. Generally you would want the ATP environ- ment variable to be a path to a subdirectory off of your home directory. Use a descriptive name such as `atpmail' or `qwkmail' for this directory. The OS-9/68000 version of ATP uses the TERMCAP library and looks for the terminal type in the environmental variable TERM. Use the "setenv" command to set the correct terminal type. Your termcap file should define the sequences for cursor movement, cursor up, cursor down, cursor left, cursor right, and the pad character. SHELL SYSTEM COMMANDS When at the ATP command prompt, you will be able to exe- cute many common Unix commands directly: cat, cd, cp, echo, df, du, less, ln, lpr, ls, man, mkdir, more, mv, pwd, cwd, rm, rmdir, set, sort, sync. Under the MS-DOS version the following commands are avail- able: cd, chkdsk, copy, del, dir, md, mem, more, mkdir, print, rd, rmdir, set, sort, type, xcopy. Under the OS-9/68000 version the following commands are available: "del", "dir", "makdir", "deldir", "chd", "copy", "list." CONFIGURATION Before using ATP for the first time, you will have to edit its configuration file which you may call either `atprc' or `.atprc' . This file contains a list of information which tells ATP where to find your mail packets, what edi- tor to invoke for entering messages, how many lines your screen has. Below is a typical configuration file. IMPOR- TANT! A space must reside on either side of the `=' sign for correct parsing to take place. ------------------------------------------------------- user = PAUL DRAKE editor = vile reply = /usr/spool mail = /usr/spool archiver = zip -jk unarchiver = unzip -xjo speller = ispell ansi = on graphics = on charset = latin1 screenlen = 25 qlist = ls -lt *.qw? | cut -c 34- | less tagstyle = fido tagline = Why buy a cow when the milk is free? autotag = on ------------------------------------------------------ user Your name goes here. It must be spelled exactly as it appears on the bulletin boards where you are regis- tered. editor The name of the editor which you will use to edit your replies. reply This is the path to your directory where you keep reply packets for uploading. mail This is the path to your directory where downloaded message packets are kept. archiver This is the name of the program used to prepare your reply packet for uploading. Normally this is zip. The switches `-jk' tell zip to create zips without path- names and to emulate PKzip. These switches aren't absolutely needed put could be helpful in certain situations. Note that on earlier releases of zip and unzip for Linux that there were bugs. Please acquire the most recent versions of zip and unzip for your system which is compatible with the BBSs you fre- quent. Note that version 1.9 of Zip is incompatible with most zip archivers used in the BBS community. Most BBS use a version of zip compatible with PKzips version 1.10. Consult your sysop if in doubt. unarchiver This is the name of the program used to extract the data files from your QWK mail packets. Normally this would be unzip. The switches `-xjo' tell unzip to extract files while junking path names, and to over- write existing files without prompting. These switches may not always be necessary but may be help- ful in certain situations. Note that on earlier ver- sions of zip and unzip for Linux that there were bugs. Please acquire the most recent versions for your system. speller This line defines the name of the spelling checker you wish to use to check the spelling of your replies. Ispell is recommended because of its inter- active design. It is available in source code form at When Gravity Fails BBS or Brodmann's Place BBS. See end of document for phone numbers. ansi This configuration switch can be set to either `on' or `off'. It defaults to `off' but most Linux users should set this to `on'. This controls the placing of the cursor on the screen and other screen attributes. graphics When graphics is set to 'on' ATP will use vt100 line graphics characters to emulate the DOS line graphic character set. Linux users will want to set this 'on'. If your terminal or system console is unable to display the vt100 line graphics set then set this 'off' (e.g. 386BSD users ). If you want to see if your terminal is capable of displaying vt100 graph- ics, type the command 'graphics' at the ATP command line. It will toggle this mode on and off, displaying a boxed message. If you toggle graphics 'on' and instead of a pretty graphics box on a reverse field you view an ugly box composed of q's and a's then you may safely assume that your terminal will not support vt100 line graphics. Note that line graphics is independent of which character set you choose. If your terminal uses the msdos character set and dis- plays it correctly, there is little point in choosing this option. However, just because your operating system is running on a PC, DO NOT assume that is uses the MS-DOS character set. charset Most QWK packets use the MS-DOS character set to rep- resent foreign language and graphics characters. How- ever most Unix systems do not recognize the MS-DOS character set mappings. If your system does then you should set charset equal latin1 character set (e.g. Linux) then you will want to set charset equal to 'latin1'. If your system is unable to display any 8 bit characters you will want to set this to '7bit' (8 bit characters will then be mapped to their closest 7 bit counterpart). Please see the file "atprc" for more details. Here are some suggested settings: Table 1. Character Set Options for atprc Variables --------------------------------------------------- system | charset | graphics | | Linux | latin1 | on | | 386bsd | msdos | off | | VT100 | 7bit | on | | generic | 7bit | off | | MS-DOS | msdos | off | | -------------------------------------------------- screenlen This configuration setting tells ATP how many lines your screen uses. This depends on the type of video card which you are using and also on the type of ter- minal emulation which you have selected. Valid entries are in the range of 3 to 300. qlist Used for listing QWK packets. This configuration entry is a command line which will be executed any- time you type `qlist' at the ATP prompt. ATP will change to your mail path directory and execute this command line. The example here when invoked will list all the quick packets in your mail directory sorted by time and only displaying the size, date, and name of the packets. It is piped into `less' which is the GNU version of `more'. You may delete this entry or modify it if it doesn't do what you want. A simple default entry is already set internal to ATP. tagstyle This switch sets the default style used in your mes- sage taglines. It defaults to normal. By setting this to `tagstyle = fido' atp will start up using FIDOnet style taglines. See later section on taglines for more information. tagline This is used to set your persistent tagline which can always be called back immediately from the command line. See section on taglines for details. autotag By default, ATP will randomly select taglines for your replies. This feature may be turned of from the command line or by setting autotag to "off". Your taglines should be stored in the file "taglines.atp" in the same directory as your atprc file. COMMAND LINE EDITOR The OS-9/68000 version of ATP does not use the command- line editor. ATP uses the Rich Salz and Simmule Turner command-line editor. This provides a simple but powerful emacs-like command-line editing interface to its users. Previous commands may be recalled by scrolling through the command history with the arrow keys. A line may be edited before it is sent by typing either control characters or escape sequences. A control character, shown as a caret followed by a letter, is typed by holding down the ``control'' key while the letter is typed. For example, ``^A'' is a con- trol-A. An escape sequence is entered by typing the ``escape'' key followed by one or more characters. The escape key is abbreviated as ``ESC.'' Note that unlike control keys, case matters in escape sequences; ``ESC F'' is not the same as ``ESC f''. An editing command may be typed anywhere on the line, not just at the beginning. In addition, a return may also be typed anywhere on the line, not just at the end. Most editing commands may be given a repeat count, n, where n is a number. To enter a repeat count, type the escape key, the number, and then the command to execute. For example, ``ESC 4 ^f'' moves forward four characters. If a command may be given a repeat count then the text ``[n]'' is given at the end of its description. Please see the man page editline.3 for more details. The following are a list of the basic control characters and commands: ^A Move to the beginning of the line ^B Move left (backwards) [n] ^D Delete character [n] ^E Move to end of line ^F Move right (forwards) [n] ^G Ring the bell ^H Delete character before cursor (backspace key) [n] ^I Complete filename (tab key); see below ^J Done with line (return key) ^K Kill to end of line (or column [n]) ^L Redisplay line ^M Done with line (alternate return key) ^N Get next line from history [n] ^P Get previous line from history [n] ^R Search backward (forward if [n]) through history for text must start line if text begins with an uparrow ^T Transpose characters ^V Insert next character, even if it is an edit command ^W Wipe to the mark ^X^X Exchange current location and mark ^Y Yank back last killed text ESC start an escape sequence (escape key) ^]c Move forward to next character ``c'' ^? Delete character before cursor (delete key) [n] Note: use the up/down arrow keys to recall previous commands. COMMANDS SUMMARY What follows is a summary of the commands available inside ATP. The most important are: `load', `review', `j',`n',`r', `e', and `scan'. These will be presented first. Remember that you may always type `help' for a brief summary of commands. help The `help' command will display a brief summary of available commands. load [ bbsname | bbsname.qwX ] This command is used to get a QWK packet from your spool directory and load it into the reader for view- ing. It takes one argument, the name of the BBS or the explicit name of the mail packet. If you just give the name of the BBS it will search for the packet names `bbsname.qwk'. You may also name the packet explicitly. In the above example the `X' rep- resent the letter `k' or typically the digits 0-9, although any printable character is valid. NOTE: If you want to load a QWK packet with other than the extension `.qwk' you must enter it explicitly. Exam- ple: load zer0g.qw4 review bbsname The review command is used for reviewing the BBS archives previously loaded into the reader. It takes one argument, the name of the BBS without any exten- sion. DO NOT add the `qwk' file extension with this command. The short form of this command is `rev'. Example; review brodmann rev running <cr> A carriage return alone will read the next message. j [conf. name | conf. number ] The `j' command stands for `join' and it is used for changing conferences. It must be followed by either the conference name or the conference number. n The `n' command will join the next active conference. a The `a' command will display the current message again. + The `+' command will go forward one message. - The `-' command will go backward one message. r The `r' command is used to enter a reply to the cur- rent message. Be sure you have chosen your tagline before entering `r'. You will be prompted allowing you to change the reply information. When prompted for security you may answer `n' or `r' which respec- tively stand for `none' and `receiver only' (private message) security. c The `c' command is used to enter changes to a previ- ous reply. This command Is valid only in the replies conference. It will re-invoke the editor for the current message. The old message is killed along with its tagline. The tagline active at the time this com- mand was invoked will be the new tagline for the edited reply. Note that that in the context of the reply conference, the `e' command has the same effect as the `c' command--change reply. p The `p' command is used to toggle message security between "private" and "public" for your reply mes- sages. When a message is private, a warning to this affect will be highlighted in the bottom right of the message header. e [(no argument) | conf. number | conf. name] The `e' command with no arguments will enter a mes- sage in the current conference. Again, choose your tagline before entering your message. The `e' com- mand may be followed optionally by the name or number of the conference where you'd like to enter your mes- sage. Upon invoking `e' you will be presented some choice as to subject, addressee, and message secu- rity. Note that this command behaves differently if the current conference is either the REPLY or PERSONAL conference. If you are in the PERSONAL message con- ference, this command is completely disabled because it makes no sense to enter a message in the personal conference (you CAN reply to messages though--use the `r' command). If you are in the REPLY conference, this command will re-edit the current message. It does not enter a new message. head The `head' command will toggle the automatic reply header on and off. The reply header is a sentence at the top of a quoted reply message which will mention the name of the author of the quoted message, who it was written to, and on what date it was written. If you don't want this style in your replies then you may turn it off with the head command or just edit it out when composing your reply. reset The `reset' command is used to set the conference message pointer to the highest message which you have read. It looks at the value of the current message and resets the highest read pointer to that value. This is useful if you wish to quit in the middle of re-reading a conference but would like to save your place marker. scan Will scan forward from the current message displaying message headers. You will be prompted after each screen whether you wish to continue scanning. conf The conf command will display a list of all available conferences on a particular BBS. find The find command will search the current conference for any text that follows it. It is not case sensi- tive. For example: find paul drake will display messages containing the text "Paul Drake" or "PaUl dRakE" and so on. After finding some text, use the `next' command to repeat the search. Note that any spaces after the first one following `find' are significant. Thus, find paul drake is NOT the same as find paul drake'. next The `next' command is used to repeat the search ini- tiated by the `find' command. qlist The qlist command will display a list of all QWK packets in your mail directory. See the configuration section for details. ! [options] This command will shell you out of the program into the system. Type `exit' to return. You may follow this command with any valid command line which your operating system will recognize. cls Will clear the screen display time Will display the current date and time. date Will display the current date and time fido The `fido' command will toggle the current tagline style. See section on taglines for more information. news The `news' command will display the current news file from the BBS. welcome The `welcome' command will display the current board's welcome message. files The `files' command will display the new files list from the current BBS. m The `m' command will toggle the ansi mode on and off. g The `g' command will quit ATP. q The `q' command will quit ATP. It is the same as the `g' command. s [filename] The `s' command will save the current message to a specified text file. tag The `tag' command is used to set tagline options. See the section below on taglines for details. TAGLINES ATP supports either FIDO or regular style taglines. In addition ATP uses three types of taglines: persistent, run-time, list. You have 1 persistent and 1 run-time tagline. Your list taglines must be kept in the file "taglines.atp" which should be in the same directory as your atprc. The purpose of the persistent tagline is that it is always there for you to recall and use. You may choose to use other taglines but the persistent tagline will still be there when you want it. The run-time tagline is one you yourself enter at the command line. Should a bit of whimsy strike you, you can use it right away with- out editing the tagline file. At any one time there is only one active tagline which may be viewed by typing the command `tag ?'. Before entering your message choose your active tagline. You may pick from the list, use your per- sistent tagline, or type a run-time defined tagline at the prompt. You also have the choice of toggling FIDO or regu- lar style tagline by typing the command `fido' at the com- mand line. Here is a summary: persistent Defined after the `tagline =' statement in the con- figuration file. This tagline is stored in a stack with the run-time tagline. Typing `tag swap' will copy the stack into the current active tagline. Typ- ing `tag swap' twice in a row will roll the stack. The persistent tagline is good for a tagline which you regularly use such as one containing place of message origin. run-time Defined at the ATP command line. If you feel like adding an impromptu tagline just type `tag' followed by your text. Example: tag Laurel and Hardy fan club This will change the active tagline to: ... * ATP/Linux 1.4 * Laurel and Hardy fan club. list A list type tagline is just a tagline stored in the plain text file "taglines.atp". If you have selected the auto tagline feature, ATP will choose a tagline at random from your "taglines.atp" file every time you enter a reply. You may also type `tag random' at the tagline to re-select at any time. Taglines may be selected directly by typing `tag list' to view your list of taglines, and then typing `tag N' to choose a numbered tagline directly (`N' would be the number of the tagline in the list as it is viewed). If you wish to add or delete taglines from "taglines.atp" you should use your favorite text editor. TAGLINE COMMAND The `tag' command is the basic command for setting and changing taglines. ATP echoes any changes in tagline to the screen so you may be certain as to what the current tagline is. If in doubt, just type `tag ?'. Here are the possible variations on `tag': tag help The `tag help' command will display the special help menu for taglines. tag swap The `tag swap' command will swap move either the per- sistent or the run-time defined tagline into the cur- rent tagline buffer. Any list defined tagline will be removed from the buffer. Alternately typing `tag swap' will toggle the current tagline between persis- tent and run-time defined. tag list The `tag list' command will display a list of all available taglines. tag n The `tag n' command will set the current tagline to the tagline in the list designated by the number `n'. tag ? The `tag ?' command will display the current tagline. tag auto The `tag auto' command will toggle automatic tagline selection ON or OFF. tag random The `tag random' will choose a random tagline for you. It may be used with either automatic selection disabled or enabled. The auto tagline mode itself uses this command after every reply to regenerate a new tagline. Try it out a few times to familiarize yourself with it. fido This is a command which toggles the tagline style between FIDO style taglines and regular style. This is provided because FIDOnet has specific rules about tear lines and high ascii characters. Here is an example of a regular tagline followed by an example of a FIDO style tagline: --- # ATP/Linux 0.3 # This is a regular style tagline. ... * ATP/Linux 0.3 * This is a FIDO style tagline. SPECIAL KEYS With release 1.4 some support for special keys have been added. This is still being developed and may change. If you would like to try the special keys here are the map- pings. Note: support now is only for vt100, Linux, and MS- DOS consoles. key command ------------------------------------------------------------- <f1> help <f2> tagline help <f3> view taglines <f4> list available quick packets <f5> show terms of license <f10> 'next' for text search. <home> goto first message in conference [keypad upper left] <end> goto last message in conference [keypad lower left] <page up> view messages in reverse order [keypad upper right] <page dn> view messages in forward order [keypad lower right] <center '5'> 'N' either 'next' or 'no' (depends on context) <up arrow> recall previous command in history <down arrow> recall next command in history HISTORY Version 1.4 September 1993 -- OS-9/68000 version of ATP. Now ATP uses the Microware termcap library for terminal functions. The ANSI escape sequences hard- coded into output strigns have all been removed. The "ansi" switch was kept for those who might want it. The code was de-ANSI-fied for the Microware version 3.2 K&R C compiler. The editline library is not used in this version. Version 1.4 November 1992 -- second release of ATP Now ATP includes a separate conference for replies. Replies may be killed with the `k' command or secu- rity toggled with the `p' command. The `find' com- mand and `next' command were added for text search. The Rich Salz and Simmule Turner line editing library is now included. This gives powerful Emacs style com- mand line editing and history recall. Please check the separate copyright notice regarding this library. Three character sets are now supported: ISO Latin1, 7bit, and MS-DOS. On terminals which support vt100 line graphics, MS-DOS line graphics are translated appropriately. In addition, for some terminals, spe- cial function keys are now supported. Limits on number of conferences per BBS is now set at 8192 with dynamic memory allocation for supporting data structures. Message size limit has been increased from 32K bytes to 150K bytes, roughly 3000 lines of typical message text. Limits on the number of taglines have been removed. Taglines are now stored in a separate tagline file "taglines.atp". Taglines may now be selected randomly (automatically or manually) as well as directly. Bug fixes and gen- eral code cleanup also were done. Code has been brought into stricter compliance with ANSI and POSIX standards. Sorry K&R. No matter what your system GNU GCC is recommended for compiling ATP. ATP has been compiled and tested on a number of sys- tems for this release including Esix, Linux, Sys5r4, 386bsd, and MS-DOS. For MS-DOS it is recommended that D.J. Delore's port of GNU GCC be used. This is a very nice compiler and it will compile Unix source code very nicely. It requires a 386 or better computer. ATP will also compile under the large model of Bor- land's Turbo C but the limits are smaller and the Salz/Tumlee command-line editor is absent. Version 1.3 July 1992 -- first release of ATP McWilliams. Character set translation DOS/Linux, Linux/DOS. Personal mail alarm. Personal mail confer- ence. Real reply headers, real time and conf. num- bers. Command line processing. Improved command pars- ing. Rewrite fget() to handle pathological con- trol.dat files. Taglines and tagline management. Ansi editing of entries. Replies queries: save, abort, edit. Message header scanning. Bug fixes. Improved message quoting. Correction of conference Autojoin(); Tested under Linux 0.96c and Esix R.4.0. Version 1.2 April 1992 -- first Unix/Linux port of Azer- TyuioP. Salazar. Unix-izing Dosisms. Conversion of path names. Writing new string comparison functions. Reworking system.c and system.h modules for portabil- ity. First version to unarc packets and read them. Improved handling of control.dat parsing. Introduc- tion of array to track real conference numbers versus conference ordinal numbers. Version 1.1 November 1990 -- Cougnenc releases AzerTyuioP code. Cougnenc. Code to experimental QWK reader AzerTyuioP is released for MS-DOS. Primarily useful as tool for studying QWK packets. Cougnenc had no documentation on the layout so this work was empirical in nature. Includes both French and English capabilities, set- able at compile time. Reader creates archives of received messages. THANKS Many thanks to Rene Cougnenc for his AzerTyuioP from which much of ATP is derived. His experimental reader is what made this possible. Also thanks must be given to Mark Salazar who provided the first quasi-functional Unix ver- sion of AzerTyuioP which was able to un-archive packets and read mail. He spent quite a bit of time Unix-izing the DOS-isms out of the code. Thank you Mark. Also thanks to Dane Beko, Patrick Lee, Ron Smith, and David Fox who have provided useful suggestions and bug-reports. David was particularly instrumental in testing ATP under 386bsd. Thomas McWilliams developed the Unix version of ATP that was ported to OS-9/68000 by William R. Hamblen.