home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / comm / portalx1.lha / PortalX.Docs < prev    next >
Text File  |  1992-11-13  |  40KB  |  866 lines
  1. PORTALX - THE AMIGA AUTOMATED "FRONT-END" FOR THE PORTAL ONLINE SYSTEM [sm]
  2.  
  3. NOTE: A description of changes from V1.10 to V1.30 is in the file
  4.       "Changes.Txt".
  5.  
  6. SYSTEM REQUIREMENTS:
  7.  
  8. - Any Amiga running Operating System 2.04 or greater.  
  9. - A minimum of two floppy drives required.  A hard disk preferred.
  10. - A valid current account on The Portal Online System [sm]
  11. - A modem and telephone line with which to dial the Portal Online System
  12.  
  13. LEGAL STUFF:
  14.  
  15. PortalX, the executable program, and this documentation file
  16. are all Copyright 1992, Steve Tibbett, All Rights Reserved.  
  17.  
  18. You may redistribute this archive file anywhere you please however
  19. you MUST retain ALL the original unmodified pieces within it.  If you
  20. redistribute the original archive as you downloaded it from Portal,
  21. do NOT add anything to it and do NOT remove anything from it.  Please
  22. respect these distribution requirements.  Do not attempt to modify
  23. the PortalX program in any way.  Source code is not available.
  24.  
  25. The archive file from which you extrated this documentation should have
  26. contained the following:
  27.  
  28. Changes.Txt - ASCII text, listing PortalX changes since V1.00
  29. Friends - A friends list with Harv Laser and Steve Tibbett in it.
  30. PortalX - the executable program itself
  31. PortalX.info - icon for the program (Thanks to Mike Crossmire for the Icon!)
  32. PortalX.Docs - the file you are reading now
  33. PortalX.Docs.info - icon for this text file
  34. Problems.Txt - help with some common problems
  35. Problems.Txt.info - icon for this text file
  36. Pages.Txt - ancillary index file used by PortalX
  37. Sprintnet.script - login script for PortalX for SprintNet callers
  38. Tymnet.script - login script for PortalX for Tymnet callers
  39. Direct.script - login script for Portal direct callers
  40. xprzmodem.library - Amiga system library to be copied into your
  41.   SYS:Libs directory, required to use PortalX
  42.  
  43. ---------------------------------------------------------------------------
  44.  
  45.     PortalX V1.30 Documentation
  46.     by Steve Tibbett and Harv Laser
  47.  
  48.  
  49. INTRODUCTION
  50.  
  51. The Portal Online System ("Portal") is an excellent service for Amiga
  52. users. It offers more files than any other Amiga service, and at very
  53. low rates.  However, the user interface on Portal is less than ideal
  54. - the simple task of entering a message can become complicated on
  55. Portal.  While reading messages is easy, setting Portal up to read
  56. messages is not easy.
  57.  
  58. PortalX makes these operations much easier, and gives you a familiar
  59. interface to use when reading and writing messages.  PortalX uses
  60. your favorite text editor to create messages, and complies with as
  61. much of the Amiga Style Guide as it can.  Once you have PortalX set
  62. up and working for you, the only reason to manually log onto Portal
  63. with your usual terminal program will be to search for and download
  64. older files, and to participate in the live, nightly chats, or to use
  65. Portal's Internet Services facilities.  PortalX does not deal with
  66. live chatting or Portal's Internet Services, and further, PortalX is
  67. a completely free-standing executable program - it does not run
  68. "inside" of or "alongside" your current terminal program.
  69.  
  70. PortalX requires Kickstart 2.04 or later.
  71.  
  72. PORTALX IS SHAREWARE
  73.  
  74. I'm putting this right at the start of the documentation because I
  75. feel this is important.  I spent a lot of time working on the original
  76. PortalX, and now realize how much more time I could spend working on
  77. it.  I would like to add quite a few things to PortalX and I can't 
  78. afford to keep working on it without making any money back from it.
  79.  
  80. I wanted to keep PortalX as freeware, which the first version was
  81. released as, but when I released the first version, it was with the
  82. intention of being "done" with it, of not working on it anymore, but
  83. response has been so good on Portal that I've spent some time working
  84. on this new version, especially on the problems that plagued early
  85. users, such as the difficulty of setting up Portal.
  86.  
  87. If better time accounting appeals to you, or perhaps a database of
  88. messages (rather than just the current session's worth), or an easy 
  89. way into and out of chat mode - you get the picture - then consider
  90. registering PortalX.  If nobody registers, it's not going to get
  91. these features.  If people register, it will.
  92.  
  93. Registering PortalX will give you access to the closed PortalX area
  94. on Portal.  I will be posting new versions there more frequently
  95. than the public releases - but the public version if PortalX will
  96. have all it's features enabled.  It just might not be as current
  97. as the registered version.
  98.  
  99. To register PortalX, send a cheque for $30, payable to 
  100. Steve Tibbett, to:
  101.  
  102.        PortalX Registration
  103.        2710 Saratoga Pl. #1108
  104.        Gloucester, ON
  105.        K1T 1Z2 Canada
  106.  
  107. Be sure to mention your Portal ID when registering!  (Otherwise I
  108. won't be able to let you into the PortalX area).
  109.  
  110. How much work goes into future versions of PortalX will depend
  111. entirely on how many users register.  A program worth using is a
  112. program worth registering, and I hope you appreciate the opportunity
  113. to see how the full, uncrippled program performs without having to
  114. send in your money first.  Thank you.
  115.  
  116.  
  117. HOW PORTAL WORKS
  118.  
  119. Before you can really understand what PortalX is doing, and how to
  120. make it do what you want without getting it confused, you have to
  121. understand how Portal arranges messages and files.  You don't need to
  122. know this stuff unless you start writing messages or uploading files,
  123. but it is a good idea to understand this information.
  124.  
  125.     CONFERENCE -> COLLECTION -> ARTICLE 1
  126.                  -> ARTICLE 2
  127.                  -> ARTICLE 3
  128.               COLLECTION -> ARTICLE 1
  129.                            -> ARTICLE 2.. and etc.
  130.  
  131. A conference is a list of collections.  Collections hold articles.
  132. This is a simplistic view of how Portal works, since they can set
  133. these things up however they want, but for the AmigaZone on Portal,
  134. this is how things are set up.  For example:
  135.  
  136.     FILES  ->  NEW_FILES  ->  NewFileOne.LZH
  137.                           ->  NewFileTwo.LZH
  138.                ETC_FILES  ->  AnotherFile.LZH
  139.                           ->  YouGuessedIt.LZH
  140.  
  141. This is how the file area is set up on Portal.  So when PortalX
  142. speaks of wanting the name of a "Collection", it wants what you would
  143. normally call a message or file area.  When getting a file catalog of
  144. a lot of areas at once, you tell PortalX that the page number you
  145. have given it is a Conference, and it knows that that page contains
  146. Collections, not Articles.
  147.  
  148. I mentioned Page Numbers there.  Everything on Portal has a page
  149. number or "go" number, and this is normally right at the top of your
  150. terminal screen if you use Portal in its "screen" mode or at each
  151. page break if you use Portal in its "line" mode.
  152.  
  153. To get to any page number on Portal, from any prompt, you can type
  154. "Go 123.45" where 123.45 is the page number you want to go to.  Page
  155. numbers for an article will change when the article is moved, but
  156. otherwise they are constant.  Every collection, every message, every
  157. file on Portal has its own unique "go" number.
  158.  
  159. The page numbers themselves say something about the content of that
  160. page.  A page number ending in ".1" is a root menu, ".3" is a
  161. conference, ".3.nnn" is a collection, and ".3.nnn.nnn" is an article.
  162. In the AmigaZone, "4842.3" is the file library, "4842.3.32" is the
  163. new files area, and a file in the new files area might be called
  164. "4842.3.32.104".
  165.  
  166. The message area in the AmigaZone is a little different, in that each
  167. message area is a conference, and then each message topic is a
  168. collection with articles within that.  Whereas "4842.3" is all the
  169. AmigaZone file areas, "16046.3" is one message conferece - the
  170. programming message section.  Within this area, ie, "16046.3.111" you
  171. might find a collection of messages on a particular topic, and then
  172. the messages in that topic will be "16046.3.111.1" and on up.
  173.  
  174. THE PAGE LIST
  175.  
  176. PortalX has a list of page numbers, kept in a text file called
  177. "Pages.Txt", that you can view and edit from within PortalX.  When
  178. you want to enter a message, or upload a file (for example), you have
  179. to pick the page number you want the article to be posted to,
  180. otherwise PortalX has no idea where to put it!  You do this by
  181. selecting the "< pick" gadget and then choosing an appropriate page
  182. from the page list.
  183.  
  184. It is important that you choose an appropriate page:  If PortalX
  185. wants a Conference, and you select a Collection, (or make any other
  186. similar mistake), PortalX will likely tell you of your mistake, but
  187. if PortalX misses it, then when it tries to send your article (or
  188. however it tries to access that page) it will get lost.  (Getting
  189. lost is covered later)
  190.  
  191. INSTALLATION OF PORTALX ONTO YOUR AMIGA
  192.  
  193. There are a number of simple steps involved in installing PortalX.
  194. First is the physical installation - copying PortalX into it's home
  195. directory.
  196.  
  197. Make a directory for PortalX, or format a floppy disk for it if you
  198. are running off floppies, and place PortalX either in the directory
  199. you have made, or on this floppy disk.  This will be PortalX's home,
  200. and you should always change to this directory before starting
  201. PortalX if you are using the CLI.  Example: you make a directory on
  202. your hard drive partition DH1: called "Portal".  To change to this
  203. directory from a CLI/Shell prompt you would type "cd dh1:portal" and
  204. hit <return>.
  205.  
  206. From Workbench, this happens automatically.  (Installation from
  207. Workbench is even easier.  Create a new drawer for PortalX, and drop
  208. it's icon into this drawer).  Copy the Pages.Txt as well, to wherever
  209. you put PortalX.
  210.  
  211. PortalX uses the XPR external protocol method of doing file transfers,
  212. which means you will need to have an "xprzmodem.library" installed
  213. in your libs: directory.  Copy xprzmodem.library to sys:libs from
  214. a CLI/Shell or use your favoriate "dirutil" program to copy it.
  215.  
  216. PortalX will create subdirectories in it's home directory as needed.
  217. Mail, MailSend, and Subs are the three directories for storing
  218. incoming mail, outgoing mail and requests, and subscriptions, in that
  219. order.  You don't need to worry about these directories, in general,
  220. unless something goes wrong.  The items in the Mail Send directory
  221. are documented later.
  222.  
  223. CONFIGURATION
  224.  
  225. Once you have installed PortalX, run it.  You will see a screen with
  226. a single window full of buttons.  Click on the Configure button. Here
  227. you will see buttons for summoning various other windows, and some
  228. string gadgets.
  229.  
  230. "Login Script:" is where you will put the name of the login script
  231. that PortalX will use to log into Portal.  Typically this will be
  232. "Login.script" but if you have multiple ways of getting to Portal,
  233. you may need to switch scripts.  Login scripts are discussed later.
  234.  
  235. "Download Path:" is where binary files that you download will be
  236. placed.  This defaults to "RAM:" but most people have a place where
  237. they put new downloads, and that is what you should put here.
  238.  
  239. "Log File:" is where you choose a name for the PortalX log file.  You
  240. can also choose to leave this empty.  If this is a valid filename,
  241. then PortalX will write the text from the Report window into this
  242. file, so that you will have a permanent summary of what you have done
  243. in PortalX.
  244.  
  245. "Pop to front when done?" tells PortalX whether or not to pop it's
  246. screen to the front of all other screens every time it finishes an
  247. online session.
  248.  
  249. "Skip Message of the Day?" tells PortalX to ignore the daily login
  250. message.  PortalX will normally open a window with the contents of
  251. the message of the day, and you can close this window any time during
  252. the session.  Picking this box will cause PortalX to never open this
  253. window.
  254.  
  255. In "Set Editor..." you are asked for the name of a text editor.  This
  256. must be the COMPLETE PATH to your text editor - not just it's name.
  257. Even if the editor is in C:, you must say "C:Editor" or PortalX will
  258. not find it. PortalX will use this editor whenever it wants you to
  259. write text. The Commodore "C:Ed" editor is not good for this, since
  260. it runs on the Workbench screen.  You will want to put the name of an
  261. editor here that runs on it's own screen, or one that runs on a named
  262. public screen.  The name of the file to be edited is appended to this
  263. string, and then that string is passed to AmigaDOS to be executed.
  264. When AmigaDOS returns, the file is looked at, and if it is unchanged,
  265. then the edited file is not used.
  266.  
  267. Some text editors "detach" themselves from the shell window when run,
  268. meaning that the prompt comes back at the shell before you have even
  269. begun editing.  You must tell your editor not to do this, to work
  270. with PortalX.  For example, in TurboText, there is a WAIT option to
  271. ask it to wait until the editing is done before returning, and there
  272. is a -STICKY option in CygnusEd to do the same thing.  The EMACS
  273. editor that comes with Workbench is a good editor to use here, if you
  274. don't have any other text editor.
  275.  
  276. If your text editor supports opening its window on a public screen,
  277. and you can set this on the command line, then do this here.  For
  278. example, with TurboText, you would say "TURBOTEXT:TTX WAIT SCREEN
  279. PORTALX".  PortalX's public screen is called "PORTALX", all upper
  280. case.
  281.  
  282. In "Set Signature..." you supply the names of files containing
  283. "Signatures" that you want to use, when writing either Mail messages,
  284. or normal public messages.  A signature is your usual signoff at the
  285. end of a message.  You can use no signature if you like, or you can
  286. use the same filename for both signatures.  The signature is added to
  287. the file before your text editor is called, so you will see the
  288. signature while writing the message.  Clicking on the "< Edit" gadget
  289. next to the signature names will load your text editor (assuming you
  290. have configured it already) for editing the Signatures.
  291.  
  292. In "Set Serial..." you tell PortalX where to find your modem.  The
  293. built-in serial port is called "serial.device" unit 0, but if you
  294. have any other serial port or internal modem, you will have to change
  295. this.  The name of the device, and the unit number, should be
  296. included in the documentation for your device.  The baud rate when
  297. logging in will be set to the number you choose here - all
  298. communications with your modem will happen at this rate.
  299.  
  300. You also tell PortalX how to hang up.  PortalX needs to hang up the
  301. phone (your modem) at the end of each session, and there are many
  302. ways to do this.  The two most common, depending on your modem
  303. settings, are to either just drop the DTR line, or to send the modem
  304. a "+++", then an "ATH" with a one second delay surrounding the "+++".
  305. PortalX will use one of these methods depending on what you tell it
  306. here.
  307.  
  308. "Set Screen Mode..." is only available if you are running Workbench
  309. 2.1 or later.  Picking this option will bring up a screen mode
  310. requester, where you can choose a new screen type to run PortalX on.
  311. If you do not have Workbench 2.1, you can use the "i" and "n" 
  312. characters to tell PortalX, when started from the CLI, which screen
  313. mode to use:  Interlace and Non-Interlace respectively.  If you save
  314. the configuration after running it this way, then that will be your
  315. screen mode for future sessions.
  316.  
  317. If you "Save" your configuration, it will be the same the next time
  318. you load PortalX.  "Use" will make the changes for this session only
  319. - quitting PortalX will cause it to use the last saved settings the
  320. next time you run it.  The PortalX config file is called
  321. "S:PortalX.Config".  When you save your configuration, some other
  322. things are saved as well, that are not set in the Config window.
  323. These are: The path for saved messages, and the size of the message
  324. and mail read window, and the settings in the Session Options window.
  325.  
  326. The "Check In" button is discussed later on.
  327.  
  328. The "PortalX Support" button is a button you can push to get PortalX
  329. help (assuming you've already gotten PortalX working).  This button
  330. automatically directs a message from you into the PortalX message area
  331. in the AmigaZone on Portal.
  332.  
  333. THE LOGIN SCRIPT
  334.  
  335. PortalX has to log into Portal for you.  To do this it uses a script
  336. file, whose name you can set in the Configuration section in the
  337. program.
  338.  
  339. Login Script Commands:
  340.  
  341.     @    Set maximum wait time in Seconds
  342.     <     Wait for the text after the <
  343.     >    Send the text after the > (Using ^ for ctrl)
  344.     #    Wait this number of fiftieths of a second
  345.     *    Same as > but shows "Sending Password" in the 
  346.         status window.
  347.  
  348. The login script is parsed right from the start, and cannot include
  349. comments or other text.  If the maximum wait time is exceeded, then
  350. PortalX will abort the login.
  351.  
  352. Sample PortalX login scripts are included with PortalX for some of
  353. the various ways of getting to Portal.  "Tymnet.script" works for
  354. tymnet nodes, and "Sprintnet.script" works for Sprintnet.  You will
  355. have to change the phone number after the ATDT to your local Tymnet
  356. or Sprintnet phone number, and of course change the Username and
  357. Password to your own.
  358.  
  359. If you have a PCPursuit account and wish to use it for your
  360. Portal hours, change the entry which reads "c portal^m" to "c
  361. portal,PCP-ID,PCP-PASSWORD^m" using your own PCPursuit account's
  362. information.  If you don't have nor use a PCPursuit account, then
  363. just leave that line alone.
  364.  
  365. If you have trouble logging in, then one of many things may be
  366. happening.  The most common is that takes a very long time to log in,
  367. or the Login script complains of a timeout.  This is because
  368. sometimes Portal takes a long time before it will ask you for your
  369. name, and sometimes it will take a long time between asking for the
  370. password and actually letting you online.  There is nothing you can
  371. do here other than be patient.
  372.  
  373. Another common problem is that Portal refuses to acknowledge your
  374. password the first time you enter it.  Your only recourse in this
  375. case is to call back.  This will normally happen more often for folks
  376. who use Sprintnet or Tymnet V.32 9600 nodes than for those who use
  377. 1200 or 2400 baud nodes. 
  378.  
  379. PORTAL SETUP: CONFIGURATION
  380.  
  381. *Note: With PortalX 1.10 and later, the Portal configuration discussed
  382. in this section can be performed automatically by PortalX.  If you
  383. select the "Configure Portal?" box in the Session Options window,
  384. then the next time you call Portal, PortalX will make all of these
  385. settings for you.  It is a good idea to do this the first time you
  386. call Portal with PortalX!  I am leaving this section in the manual just
  387. in case the automatic configuration doesn't work for some reason.
  388.  
  389. PortalX has to talk to Portal like no other program does.  It parses
  390. the ANSI sequences that Portal sends, and keeps its own internal map
  391. of what the screen looks like, and instead of dealing with
  392. information as it is sent from Portal, it waits for the end of each
  393. "Page" and then looks at it's internal image of the page and gets
  394. information from there.
  395.  
  396. This method has advantages and disadvantages.  One big advantage is
  397. that for pages that are small changes from the previous page, very
  398. little information needs to be sent for an entire new page.  But the
  399. big disadvantage is that one byte of line noise can corrupt an entire
  400. page.  In practice, it's not so bad, especially if you use an
  401. error-free connection such as MNP or V.42.
  402.  
  403. However, another disadvantage is that the information that PortalX
  404. expects has to be sent, and has to be exactly where it is expected to
  405. be.  If you haven't changed your Portal configuration much from the
  406. defaults, then this shouldn't be a problem for you.
  407.  
  408. However, if you have changed the default separator, the command
  409. prompt, or how the menus are laid out, then it may cause problems.
  410. The best way to proceed is to try PortalX with your configuration as
  411. it is, and if that fails, then set things back to the defaults.  You
  412. will need to have the help_type set to none, otherwise every page
  413. will have multiple lines of useless help information on it and
  414. PortalX will fail.
  415.  
  416. You must also make sure Portal is set to use Zmodem for file
  417. transfers.  If you are starting with the default settings, then
  418. getting PortalX to work would involve setting these things:
  419.  
  420.     set form/screen/header/help_type=none
  421.     set transfer/general/protocol=zmodem
  422.     set transfer/general/end_line=lf
  423.     set transfer/general/batch_files=no
  424.  
  425. To make these changes, log into Portal with your usual term program, 
  426. and then type those lines, exactly as you see them, at the main menu 
  427. command: prompt.  If you have made changes that you think will make 
  428. PortalX incompatible with your setup, then go to the various pages you 
  429. have changed and type Default.  This will reset the settings to the 
  430. defaults - and then you can make sure they are set properly by using 
  431. the commands above. Make sure you leave each Portal Settings menu
  432. with an "ok" command in order to save the changes. 
  433.  
  434.  
  435. PORTAL SETUP: SUBSCRIPTIONS 
  436.  
  437. ** THIS IS WHAT IT'S ALL ABOUT SO READ THIS PART CAREFULLY! **
  438.  
  439. PortalX's main function is the daily collection of "Subscriptions",
  440. and the interface it gives you for reading them and responding to
  441. them.  But first, you need to know what Subscriptions are.
  442.  
  443. On most bulletin boards and online systems, when you want to read
  444. messages from a specific area, you have to go there and read them.
  445. This would be like having to go to a different store to pick up every
  446. magazine you wanted.  On Portal, you can subscribe to the areas you
  447. are interested in, and then these are delivered to your subscriptions
  448. box as they are created.  When you read Subs, you are reading all the
  449. NEW messages that have been entered in any area that you have
  450. subscribed to SINCE you subscribed to that area.  You only need to
  451. subscribe to any area on Portal ONCE.  If you try to subscribe to an
  452. area that you are already subscribed to, Portal will tell you. If you
  453. subscribe to an area to which you are NOT already subscribed, Portal
  454. will simply reply with an "OK" meaning, okay, this area is now added
  455. to your subs.
  456.  
  457. Think of subs as your own private "clipping service" which keeps
  458. track of all new notices and files posted to your favorite areas.
  459. It's your job to first tell Portal WHAT those favorite areas are.
  460.  
  461. Subscribing to an area on Portal is easy - you just go there and type
  462. "Subscribe".  "Go there" means you can wander around Portal manually
  463. using its menu system, or you can use shortcut "go" numbers if you
  464. know where you want to go.  KEEP IN MIND THAT PORTAL GATHERS YOUR
  465. SUBSCRIPTIONS IN THE SAME ORDER THAT YOU SUBSCRIBED TO EACH AREA! So
  466. before you start collecting Subs with PortalX, you will have to log
  467. onto Portal, go to all the collections you are interested in, and
  468. Subscribe to them.
  469.  
  470. Alternatively, if you want to subscribe to ALL the message areas or
  471. ALL the file areas, then go to the conference that holds them, and
  472. type Subscribe there.  This will subscribe you to every collection in
  473. that conference.  Then if you don't want some specific collections,
  474. you can unsubscribe to those.  Subscribe and unsubscribe can be
  475. abbreviated "sub" and "unsub".  They are toggles.  You either turn a
  476. Portal area on or off for your subscriptions.  When you first joined
  477. Portal, all areas are, by default, turned off, except for the Portal
  478. News area.
  479.  
  480. The file area in the AmigaZone is a special case.  New files show up
  481. in collection #0, and after a week are moved into the other
  482. collections.  To avoid having every file show up both as new and when
  483. it is moved, you should subscribe to only collection #0, the new
  484. files collection.
  485.  
  486. So to set up subscriptions to read all new messages in the AmigaZone,
  487. and all new files, you would do this (Don't type in the text from the
  488. asterisk on, it's just comments):
  489.  
  490.     Go 4842.3.32        * Go to the New Files page
  491.     Subscribe        * Subscribe to it
  492.     Go Amiga;0;2        * Go to the AmigaZone Messages
  493.     Subscribe        * Subscribe to them
  494.  
  495. Also, I recommend that you subscribe to the PortalX message area,
  496. at least initially.  If you do not, then the "PortalX Support"
  497. button in the Config window will post any questions you ask, but
  498. since you aren't subscribed to that area, you won't see the
  499. answers!  To subscribe to this area:
  500.  
  501.     Go PortalX;0        * Go to the PortalX public area
  502.     Subscribe        * Subscribe to it
  503.  
  504. SESSION OPTIONS
  505.  
  506. The Session Options button brings up the Session Options window. Here
  507. you can change what PortalX is going to do next time it connects with
  508. Portal.  "Retrieve Mail" asks PortalX to download all your mail
  509. messages so you can read them offline.  "Kill Mail" asks PortalX to
  510. kill the mail after it has read it, so that it is not there the next
  511. time you log in.  "Get Subs" asks it to pick up all your
  512. subscriptions, with one exception:  UUEncoded files will not be
  513. gotten, rather just the first page will be.  (You can ask PortalX to
  514. download the entire uuencoded contents while reading subs).
  515.  
  516. The options you select in this window are saved when you save the
  517. configuration from the Configuration window.
  518.  
  519. "Do Requests" asks PortalX to go through the Send directory and do
  520. everything you have asked it to do.  This incldues posting mail
  521. messages, public messages, downloading files, uploading files, and
  522. getting file catalogs.
  523.  
  524. "Configure Portal" asks PortalX to change the Portal settings to
  525. those that PortalX requires.  You should do this the first time you
  526. use PortalX to call Portal, and if PortalX for some reason stops
  527. working for you (it gets lost when trying to log in), you can try
  528. "Configure Portal" again.
  529.  
  530. CALLING PORTAL
  531.  
  532. The Big Button.  When you select Call Portal, PortalX will start
  533. processing the login script, and when it is done, take over and do
  534. what you have asked it to do in the Session Options window.  You can
  535. abort the online session by clicking the close gadget in the Online
  536. Status window.  The Report window can be closed only when the session
  537. is complete.
  538.  
  539. Portal's Message-Of-The-Day will be displayed inside of PortalX in its
  540. own window which will pop up every time you log in.  You can close this 
  541. window as soon as it appears, or disable it with a button in the Config 
  542. window.  Please consider reading the MOTD window.. it contains useful
  543. and important information about what's going on, on Portal today.
  544.  
  545. It is important to keep in mind that PortalX never appends to
  546. existing data.  If you have previously downloaded 20 mail messages, and 
  547. you ask PortalX to go get mail, it will delete your existing 20 mail
  548. messages from your disk drive.  Same for Subs.  PortalX has the
  549. capabilities to let you save to another file any mail or subs 
  550. articles while you are reading them.  
  551.  
  552. When your PortalX session is complete, if PortalX picked up mail or
  553. subs, then the "Read Subs" or "Read Mail" buttons may have a hilight
  554. around them. This means that there is material here that you have not
  555. yet read.  Once you have read all the subs, and all the mail, these
  556. buttons will no longer be hilited.  Also, if you write mail, write a
  557. message, upload a file, or ask PortalX to do anything else online,
  558. PortalX will hilite the "Call Portal" button so you know there is
  559. something for it to do online.
  560.  
  561. If you want your PortalX sessions to happen unattended, for example
  562. during the early morning, then put a "c" on the command line:
  563. "PortalX c" will cause PortalX to act as if you had pressed the Call
  564. button as soon as you ran the program.  However, be warned that there
  565. is no guarantee that every PortalX session will go smoothly.  You may
  566. come home to find that PortalX has been online the whole time, thanks
  567. to some miscommunication between PortalX and Portal.  In general,
  568. however, this is an excellent method of having your subscriptions
  569. picked up during the early morning, ready for you the next time you
  570. check in with your computer.  The AmigaDOS WAIT command is an
  571. excellent and simple way to accomplish this.  If you type into a
  572. shell window:
  573.  
  574.     Wait Until 6:00
  575.     PortalX c
  576.  
  577. The WAIT command will wait until 6AM, and then let PortalX proceed,
  578. calling Portal.
  579.  
  580. READING MAIL
  581.  
  582. Pick "Read Mail" to start reading mail.  You will be shown each mail
  583. message, in a window with a few buttons at the bottom, the Read
  584. Window.  The Read Window has a few keyboard shortcuts that you should
  585. know about:  The up and down arrows will move you through the current
  586. article, and the left and right arrow keys will move you through all
  587. the articles you have downloaded.  Shift-up and Shift-down will page
  588. through the article.
  589.  
  590. When you click Reply, you will be asked who the article is to,
  591. with the default being the person who sent you the letter.  If you
  592. select Include Original, then the original message text will be
  593. prefaced by '>' and included with your signature in the text file
  594. that you will be editing as the message to send.
  595.  
  596. The read window position is saved into the config file.  To have the
  597. read window come up in a specific position, after you have gotten it
  598. to look the way you want it, go into the Config window and pick Save.
  599.  
  600. There are some menus available while reading mail messages.  On the
  601. message menu are options for saving the message to a file, or
  602. appending the message to an existing file (creating it if it does not
  603. already exist).  The Print option will send the text to the printer,
  604. and the Copy to Clipboard option will copy the entire text to the
  605. clipboard from which you could paste it into a text editor, etc.
  606.  
  607. The Keep button in the Read window will take the text you are reading
  608. and append it to the file you last appended data to using the "Append
  609. to File..." menu option.
  610.  
  611. READING SUBSCRIPTIONS
  612.  
  613. This works the same as reading Mail messages, except that you can
  614. also choose a menu option to have PortalX download the body of the
  615. article you are looking at next time you log in.  While this may not
  616. be of use for normal messages, it is a handy way of downloading files
  617. that appear in the AmigaZone New Files directory while you are
  618. reading subs, or binary files that appear in any other Portal SIG to
  619. which you are subscribed. 
  620.  
  621. While reading subscriptions, there are three extra menu options:
  622. Next Topic, Next Conference, and Goto Article.  Next Topic and Next
  623. Conference will skip articles in either the current topic or the
  624. current conference.  Goto Article will ask you for an article number,
  625. and will then take you there.
  626.  
  627. If the last two lines of an article indicate that the article is a 
  628. binary article which cannot be read, only transferred, then PortalX
  629. has sent the describe command to get the description that you see (if
  630. indeed you see a description).  To download the body of the article, 
  631. use the Download menu option. PortalX will download the file for you
  632. the next time you use it go log in to Portal.
  633.  
  634. THE FRIENDS LIST
  635.  
  636. The file "Friends" in the same directory as PortalX is read into
  637. memory when PortalX is loaded.  This file is a list of names, Portal
  638. ID's, and comments, for people you exchange mail with.  When you write
  639. a mail message or reply to one, you can click on "< Pick" next to
  640. the string gadget for the name, and pick the user's name from the list.
  641.  
  642. You edit this list in PortalX by selecting "Edit Friends List" from the
  643. main window.  To add a new friend, click on the New button and then
  644. type in the name, ID, and any comments you have.  The name is actually
  645. added to the list when you hit return in the comments field, so make
  646. sure you do this.
  647.  
  648. WRITING MAIL
  649.  
  650. To compose a mail message, pick Write Mail message.  You will be
  651. asked who the message is to, what it is about, and then dropped into
  652. your text editor.  The message will be sent next time you log in with
  653. the 'Do Requests' button selected.  You can send mail to more than
  654. one person by separating their names with commas in the To: field,
  655. such as "SteveX,Harv,Elvis" to send mail to Steve Tibbett, Harv
  656. Laser, and Elvis Presley.  Unfortunately, PortalX doesn't deal with
  657. bad usernames - if the username is incorrect, PortalX will tell you that
  658. the name is bad and ask you if you want to edit the request file that
  659. has the bad name in it, or just delete the message.  Make sure you
  660. know the current, correct, and complete address for anyone to whom you
  661. wish to send email. 
  662.  
  663. WRITING A MESSAGE
  664.  
  665. Writing a public message is more involved than writing a mail
  666. message, because of the many different types of messages involved.
  667. Specifically, you can post into a local Portal area, or you can
  668. be posting to a Usenet newsgroup.  You could also be trying to post
  669. to a Usenet newsgroup where posts are not allowed.  Usenet postings
  670. are called "articles." The person who posts an article to Usenet
  671. is called the "poster." 
  672.  
  673. You are asked for a page number to post the article into, and for a
  674. subject.  The page number must be that of a collection - not of an
  675. article you want to reply to.  Since 'Do Requests' happens before
  676. 'Get Subs', if you post a message to a local Portal message area, you
  677. will see it as a new subs article in the same session, unless you are
  678. posting to a Usenet group, in which case the article will show up
  679. sometime in the near future.
  680.  
  681. As usual, if you ask PortalX to do something that Portal will refuse
  682. to do, PortalX will get lost.  
  683.  
  684. UPLOADING A FILE
  685.  
  686. Uploading a file to Portal is much like entering a message, except
  687. that the body of the message is binary, and there is a description.
  688. PortalX wants a filename for the file to upload, and also wants a
  689. disk filename that contains the description of the file.
  690.  
  691. If you don't have a file description already written for the file,
  692. you can use the "Create Description" to create a temporary file and
  693. write a description into it.
  694.  
  695. The actual subject line of the posted file will be the filename,
  696. converted to upper case, with " - " appended to it, and then the
  697. summary field you supply here appended to that.  So if you are
  698. uploading "fred.txt", and your summary is "A new text file.", then
  699. the actual subject line on Portal would be "FRED.TXT - A new text
  700. file."  
  701.  
  702. Please do NOT upload new files to the Amiga Zone without also including
  703. a good description of the file.  Other Portal SIGs may have different
  704. rules about descriptions for their files.  When in doubt, send email
  705. to the SIG moderator and ask.
  706.  
  707. PortalX wants a page number to upload a file into.  This page has to
  708. be one that contains a list of files - a collection - otherwise
  709. PortalX will get lost.  (File collections have 3 numbers, for example,
  710. the AmigaZone new files area is "4842.3.32").
  711.  
  712. GET CATALOG
  713.  
  714. This function will pick up a file catalog from Portal.  PortalX will
  715. look for the page number it should fetch the catalog from, and where it
  716. should put it.  PortalX will figure out if you are asking for a
  717. catalog of a single area, or of an entire tree, by the page number.
  718. Feeding it "12117.3" would ask PortalX to go and build a catalog of
  719. all 700+ fish disks, which PortalX would happily do over the next few
  720. hours.  So don't ask for a Fish catalog unless you really mean to.
  721.  
  722. More explanation of this function is in order, since it can really do
  723. more than it claims to.  What this function does is go into a
  724. collection and read the titles of all the articles there.  It can
  725. also go through an entire list of collections.  Because of Portal's
  726. setup, messages look just like files - so you could give this
  727. function a page number that contained, for example, the "Rumours"
  728. AmigaZone message area, and PortalX would get a ilst of all the
  729. messages in that message area.
  730.  
  731. Asking this function to pick up a catalog of "4842.3" would give you
  732. a file similar to what Harv creates every week and posts as the
  733. AllFiles list in the Amiga Zone New Uploads library.  Thus you can
  734. now make your own AllFiles list anytime you wish!
  735.  
  736. DOWNLOADING A FILE
  737.  
  738. To download a file, you need to know the location of the file.  You 
  739. can either specify it as a complete page number, or you can give the
  740. page number of the area the file is in, and then the file number you
  741. want to get with a semicolon between them as in "4842.3.32;3" to get
  742. file #3 in 4842.3.32.  This method is less reliable than having a
  743. full page number since when files are moved, all the files after them
  744. in the list get a new number.  A file's page number is never changed.
  745.  
  746. If you ask PortalX to get a catalog, see a file you want in the catalog,
  747. and the file is not in the new files area, then you can be fairly 
  748. certain that if you ask PortalX to download it, it will still be in 
  749. the same place.  If you want a month, it might not be.
  750.  
  751. GETTING LOST
  752.  
  753. If PortalX encounters a situation it cannot deal with, it will
  754. typically sit waiting for some result from Portal, that Portal has no
  755. intention of ever sending.  In this case, PortalX will wait up to
  756. five minutes, and will then abort the session.
  757.  
  758. However, if PortalX and Portal get into a situation where PortalX is
  759. sending data and Portal is responding in some way that makes PortalX
  760. think things are proceeding properly, they may get into a mode where
  761. they could be online forever.  There are some checks in PortalX for
  762. this situation - such as repeated sending of the same page. These
  763. situations are usually caused by line noise, so if an error-free
  764. connection is possible, then try and use it.  If you typically get
  765. noisy connections, you are advised against using PortalX at all
  766. unless/until you get the line noise problem straightened out, with
  767. your modem, your modem cable, and/or your telephone company.
  768.  
  769. WARNING
  770.  
  771. PortalX's job is processing your mail and messages.  If PortalX
  772. doesn't do it's job properly, then it is possible that you could lose
  773. mail messages, subscriptions, your mail may not be posted properly,
  774. you get the picture.  PortalX could decide to stay online much longer
  775. than it should have, for no good reason.  While this doesn't normally
  776. happen in real life, it could.  I cannot be held responsible for
  777. anything this program does - use it at your own risk.
  778.  
  779. CHECKING IN
  780.  
  781. I had fun writing PortalX, and have a lot of things I'd like to do to
  782. it.  I'd like to know how many people are using the program - and the
  783. only way I can know this is if people tell me.  Rather than having
  784. everybody write me a mail message just saying "I used PortalX", I
  785. put in the "Check In" button.  Press this button once, and then the
  786. next time you call Portal, PortalX will send me a short message telling
  787. me that you are using Portal, and what version.  Please press this
  788. button, I would appreciate it.  Thanks. 
  789.  
  790. SUMMARY
  791.  
  792. That about covers it.  PortalX will let you keep up with what's going
  793. on in the message areas on Portal, download new files, post public
  794. messages, and generally get a lot more out of your Portal account.  I
  795. look forward to seeing you use it!
  796.  
  797. TECHNICAL:  THE SEND DIRECTORY
  798.  
  799. The "Send" directory in PortalX's home directory contains files that
  800. tell PortalX what to do next time it is online.  There is nothing
  801. special about these files - you can create them yourself if you like.
  802. This entire directory is searched for every online session with the
  803. "Do Requests" box checked.  Every .Data file is processed.
  804.  
  805. Some of the event types require extra information, such as the actual
  806. message to post, and this is stored in the "MailSend-%d.Txt" file -
  807. so if you manipulate the .Data files, you should manipulate the .Txt
  808. files as well.
  809.  
  810. The types of files, and what they are expected to contain:
  811.  
  812.     Upload            Upload
  813.                 [Page to upload to]
  814.                 [Filename]
  815.                 [Subject line]
  816.                 [Description filename]
  817.  
  818.     GetCatalog        GetCatatalog
  819.                 [Filename to hold catalog]
  820.                 [Page number]
  821.  
  822.     GetAllFiles        GetAllFiles
  823.                 [Filename to hold catalog]
  824.                 [Page number]
  825.  
  826.       *    Post Mail        Mail
  827.                 [Who the message is To]
  828.                 [Message Subject]
  829.  
  830.       *    Public Message        Message    
  831.                 [Page Number]
  832.                 [Subject]
  833.     
  834.     Download        Download
  835.                 [Page Number]
  836.                 [Destination Directory]
  837.  
  838.       *    Public Reply            [Page Number]
  839.                 [Subject]
  840.  
  841. Items marked with a '*' are items that require an associated .Txt
  842. file, containing the message text to be sent.
  843.  
  844. WHERE TO GET MORE HELP WITH PORTALX
  845.  
  846. A new Amiga Zone message base named "PortalX questions and answers" has
  847. been created in the Amiga Zone.  You should ONLY post questions or offer
  848. assistance to other users in this new message base.  Be sure to 
  849. subscribe to it!  Please do not burden the email boxes of the Amiga
  850. Zone moderators with PortalX questions.  Ask your questions in public
  851. so that everyone can see them and have an equal opportunity to learn 
  852. from the replies.
  853.  
  854. Please do *NOT* phone Portal Communications to ask for help with
  855. PortalX.  They are not Amiga users and will just refer you to the
  856. Amiga Zone for help.  PortalX is *NOT* sold by, nor distributed by,
  857. nor supported by Portal Communications at this time.
  858.  
  859. -----
  860. Amiga is a registered trademark of Commodore-Amiga Inc. and/or
  861. Commodore Business Machines and/or Commodore International Ltd.
  862.  
  863. "The Portal Online System" is a registered service mark of
  864. Portal Communications Inc. 
  865. -----
  866.