back2roots/padua

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

/ back2roots/padua / padua.7z / padua / uucp / AnnR09.lha / doc / Ann.doc next >

Wrap

Text File | 1992-06-19 | 23.9 KB | 513 lines

( $Id: Ann.doc,v 1.12 92/06/19 12:55:11 wasp Exp $ ) 0 Introduction 0.1 Ann - AmigaNoNews (is good news) - is yet another Amiga NewsReader. Written by Walter Mildenberger, under development since 20-Nov-90. All rights reserved. 0.2 I owe a depth of gratitude to the following people as I used (little) parts of their code for Ann: William Loftus Matt Dillon Bryce Nesbitt Gerald Malitz, and thanks to Angela Schmitt for her pattern.library (wich is included in this distribution). 0.3 NOTE: This is a beta version of Ann. Basically, this means that Ann has by no means completed yet, many options and features are still missing, others may work as expected - or they may not. Please feel free to tell me about bugs, or features you think they might be useful (see below for address), but flames are going to be forwarded to /dev/null. USE IT AT YOU OWN RISK! (Hey: it works fine for me ;-) ) 0.4 Memory requirements: Ann needs [currently] quite a large amount of free memory. People with less than 1MB are almost sure out of luck, with only 1MB you probably are going to have problems. If you have more than 1 MB memory, Ann should work without any problems. See discussion below. If ann went out of memory, it will report the problem, asking for retry or quit. You can calculate the requirements on your own: o For each newsgroup listed in the news system's active file 42 + strlen(groupname) + 1 bytes. o For each article store in your news partition about 100 bytes. o For each unread article there is allocated memory for 'Subject:', 'From:', 'Date:', 'Lines:', and in "threaded-mode" additionally 'Message-ID:', and 'References:', resulting in approximately 60 or 120 bytes respectively. 0.5: Stack Ann checks the stack on its own (depending on the actual version), it might ask you to increase the Stack (Sorry, setting stack on its own doesn't work right now). 1: Short Overview 1.1: Syntax: Ann [-a<active-file>] ; specifies an active-file (LIA) [-c] ; catch-up all articles on default (LIA) [-d<n>] ; set debug-level to [-f<Fontname>.<FontSize>] ; specifies another font, no restrictions. [-g <space-separated list of groups>] ; read [list of] group[s] before the ones specified by .newsrc. NOTE: MUST BE last option. [-i] ; ignores new entries in active-file [-l<.newsrc>] ; specifies another .newsrc [-n<NewsReader>] ; * specifies another program to display news like more. [-N] ; forces ann to not use an activefile at all. [-r] ; Require 'Lines:'-Header. See 3.4.1 [-S] ; Syncron-scan In case you have problems relating to the multitasking features of ann, you can switch this feature of. [Be warned, this causes loooong delays!] (LIA) [-s] ; screenswitch; after running an external program ann should issue a ScreenToFront() call. [-t] ; Enables threaded mode. This causes ann to resort articles with the same subject in respect to the References:-Line. (not implemented yet.) [-v] ; switches Pager to verbose-modus (showing all header infos) [-w] ; Opens a window on workbench instead of opening an own screen. "LIA" = "leave it alone unless you know what you're doing". * = obsolete. [Expirienced users should note that some options are removed.] 1.2: Files 1.2.1: required files: o UUCP's Config-file (UULIB:Config), could be specified in .annrc o .newsrc, could be specified; will be created if missing, overridden by -l 1.2.2: optional files: o Ann's config file (.annrc), [well, it's strongly recommended !] o active-file, overridden by -a [well, it's strongly recomended; Dillon-UUCP should use fixactive (see fixactive.doc) ] o UULIB:NewsGroups (only if active-file is missing) o specific fonts, overridden by -f * o Pager program like more, muchmore etc., obsolete. 1.3: Working Every line-option has priority over environment-vars (ENV:) and these over config-vars set in .annrc or UUConfig (UULIB:Config). The .annrc is searched in the following way: 1) ${username}.annrc, 2) UULIB:${username}.annrc, 3) ${HOME}:.annrc, 4) .annrc, 5) UULIB:.annrc , so you can place it where you need it... The .signature is first searched as specified in .annrc (if at all), then UULIB:${username}.signature, then UULIB:.signature. The length of the .sig is limited. This is intentionally! (read the net-etiquette if you are wondering why!). The groups are scanned and presented in the order found in the .newsrc. If you use the option -g , all specified groups are placed before the first group found in .newsrc. 2: Features 2.1: What is Ann good for ? Ann is yet another Newsreader. It is called Amiga-NN (Amiga-NoNews), because it tries to be similar to the original nn on unix. It is NOT a port from nn, but it is a threaded newsreader, so you can decide if you want to read a specific article, or a complete article-thread (a collection of articles wich have the subject in common). [Expirienced nn-users might find ann is not as similar to nn as it could be - well, I am working on that :-) ] 2.2: Ann is very cofigurable: o optionally internal or external Pager o optionally opens an own screen or a window on workbench o optionally fixed screen-size or variable screen size o optionally specific font (even proportional !) or system-font o choice of groups to be read o whatever include-char (string) you want o .signature of your choice o You can hilight specific header-keywords (internal pager only) o You can suppress specific header-keywords, toggles on/off with "v"erbose (internal pager only) Crossposted articles are to be read only once, ann uses the Xref: line. Ann is multi-tasking friendly: it interprets a break-signal as a hint to quit: it tries to close down, NOT updating the .newsrc. In fact, it uses the mt to spawn a secondary process which in fact does all the article-scanning: as soon as the secondary task has processed the first group, you can select and read articles, while the other task is still scanning new articles. HINT: Due to this fact it is NOT recommended to jump [g)oto] to a group later in the .newsrc; you might have to wait a long time. Be warned. 2.3 Due to the fact ann is still in developing, there are many features still on the wish-list and not already implemented: that are: o a deamon running in background doing the article-scanning inde- pendant from ann (and writing it to disk). o global and local kill-file (with auto-select). o automagic mail to the moderator of a moderated group if you post to such a group. o Folder-handling (like nn) o autmagic rescanning of active-file if it was changed. 3 Configuration 3.1 What configuration files are supported ? Ann uses normally (it is optional, but recommended) a configuration file called ".annrc". Similarities to the configuration files of Roland Bless' ARN are neither coincidence nor unintentional :^) Different users can use different configuration files, if you use different directories, or (more recommended) use the $Username Environment-variable. This is already described in part 1.3 (Working). Ann also uses the UUCP standard configuration file (S:UUConfig or - more likely - UULIB:Config). 3.2: How are the Keywords are interpreted ? Every line starting with a space ' ' or a hash '#' are treated as a comment. You can write what you want behind such a character, even supported keywords (which are ignored in this case). Every other line is treated as a configuration-command: Case is not significant, and every unsupported keyword is SILENTLY ignored. Please note: For most Keywords, there is a build-in default. You will reduce the probability for a fault (and will speed-up program-startup) by using them! You use the defaults by NOT specifying the keyword at all (comment it out by using a hash in the first column, or delete it completely.) 3.3: What Keywords are supported ? 3.3.1: In .annrc, the following keywords are used: NEWSSYSTEM, NEWSDIRTYPE, NEWSDIR, SAVENEWS, ACTIVEFILE, GROUPLIST, UUCONFIG, QUOTECHAR, SIGNATURE, SENDNEWS, SENDMAIL, REPLY-TO, OWNSCREEN, SCREENDATA, TEXTATTR, CLEARALL, NEWSREADER, SYNCRON, SCREENSW, IGNOREACTIVE, NOACTIVE, COLUMNS, EXTERNPRG, DISPLAYFLAGS, HILIGHTFLAGS, FQDN, VERBOSE, REQUIRELINES, USERSHELL, SENTMAIL, SENTNEWS, ANNHEADER, KILLFILE, PARENTPRI, CHILDPRI 3.3.2: In UULIB:Config, the following keywords are used: NodeName, UserName, RealName, Organization, TimeZone 3.3.3: The following Environment-Variables are used (if present). $USERNAME, $REALNAME, $HOME, $TZNAME, $TZOFFS 3.4: What do the keywords mean ? 3.4.1: NEWSSYSTEM: What newssystem are you running ? Supported systems are 'DUUCP' for Dillons AmigaUUCP-Package (version 1.15d), 'AUCPP' for Ingo Feulner's AmigaUUCP-Plus-Package, and 'CNEWS' for "Crash" Edwards port of Cnews (running on top of duucp). I am using these abbevations from now on. This is the most important Keyword; several defaults are set in dependancy of this entry, should be the first keyword. NEWSDIRTYPE: How are the newsgroups stored ? No need to touch if you have set NewsSystem. Every "normal" newspackage uses a hierarchical system, like UUNEWS:comp/sys/amiga/programmer/<article> . So does AUCPP and CNEWS. If hirachical, set it to 'YES' (or simply 'Y'). DUUCP uses a (IMHO braindead) non hierarchical system like UUNEWS:comp.sys.amiga.programmer/<article> . In this case, you would set NEWSDIRTYPE to 'NO' (or simply 'N'). To repeat myself, touch it only if you aren't using a supported newssystem ! NEWSDIR: Where are the news stored. (Default UUNEWS: for DUUCP & AUCPP, NewsArts: for CNEWS; no need to change if you have set NewsSystem properly. SAVENEWS: Where are articles you want to keep to be saved to ? (Only a default, you can specify a complete path at runtime). Every path supported by dos will do it. Default is the current directory, but you probably want to change this. ACTIVEFILE: The name of your (hopefully present) active-file. If you have set NewsSystem, the following defaults are used: NewsCtl:active for CNEWS, UULIB:news/active for AUCPP, and UULIB:active. GROUPLIST: Where the .newsrc (or grouplist, if you prefer) is to be found/created. Default is UULIB:.newsrc, you probably want to change this. The format of this file is quite intuitive : the name of the group, directly followed by either an exclamation-mark '!' or a colon ':', followed by a space and a comma-separated list of ranges of article-numbers. The exclamation-mark stands for unsubscribed, while the colon stands for subscribed. The groups are processed in the order of this file (overridden by "-g"), so you may want to edit this file, but you don't need to. You should not touch the [comma-separated] list, just move the complete line. UUCONFIG: Where your standart-uucp-configuration is to be found. Default is first S:UUConfig, then UULIB:Config, so there shouldn't be a need to change. QUOTECHAR: This is the string preceeding every line you want to quote. Defaults to ">". SIGNATURE: Where your .signature is to be found (A .signature is a file appended to every article and mail you want to write). Defaults to first UULIB:${Username}.signature, and second to UULIB:.signature. You can override this by specifying a SIGNATURE. SENDNEWS: The program which is to be called to send the news really. If you have set NewsSystem, then LIA !!! If you are using a not supported newssystem, you can set the "relaynews"-program; Three %s are substituted by (in that order) temp-file [obligatory], Username, and Realname. I.E. a correct string vor CNEWS would be: ╗NewsBin:relay/relaynews <%s -r½ (If you don't use the second and third %s, they aren't substituted - easy, isn't it ? :-]). A seconde example: for DillonUUCP (V1.15d), you would need something like ╗Postnews <%s -f %s -r "%s"½. (Don't use ╗ and ½, they are for readability only). SENDMAIL: Similar to SENDNEWS, this is the program to be called if you are writing mail. Similar to SENDNEWS, you should LIA unless you are using a not-supported NewsSystem. If you do, there are those three %s back again... I.E. a correct entry for DillonUUCp would be ╗sendmail <%s -f %s -R "%s"½. REPLY-TO: You can set an alternative Address for you, where you are to be reached INSTEAD of the original From:-Line. You might want to set this, if either your From:-address is known to fail often, or you are to be reached at the reply-to-address more easy. You SHOULD NOT set this address if it is equal to your From:-line ! (net.rules) OWNSCREEN: If set to No (or overridden by Option -w), ann opens a window on workbench. Else it will open a own screen. SCREENDATA: (Only interpreted if ann wants to open an own screen, see above). You can specify special informations for the screen to be opened: That are (in that order) <LeftEdge> <TopEdge> <Width> <Height> <Depth> <Flags> [<DisplayTags>], where the first six infos are obligatory, while <DisplayTags> is optional (and only interpreted if you are running OS 2.02 or greater). The first five infos are clear, aren't they ? The flags is a value set in NewsScreen.Flags (see your programmer documentation, so a value of 0x8000 means hires, 0x0004 means lores-interlace, 0x8004 means hires-interlace etc.) If you are using <DisplayTags>, set it to 0. You also can set <Height> (since OS 1.3) and <Width> (since OS 2.0) to -1 to use the largest possible value. <DisplayTags> is a Tag-value for SA_DisplayID (see graphics/displayinfo.h or your bindmonitor documentation for acceptable values), I.E. 0x00039024 stands for VGAPRODUCT_KEY. Default is open a largest-pssible screen in hires, and lace/nolace is cloned from Workbench-Settings (the current default public screen, that is). TEXTATTR: You can specify an alternate font, where the pattern is <FontName>.<Size> , i.e. ╗Times.15½ As you can see, even proportional-fonts are allowed! [Default is system-font] CLEARALL: Normally, every article starts at startup in the unselected-state (see 4.2 for details). If you set CLEARALL (or use Option -c), every article starts in "never read"-state. BE WARNED: If you have set this, you probably will loose articles (if you quit ann, all "never-read" articles are marked as "already read" and are NOT rescanned next time). [Default is not clear-all] NEWSREADER: Normally, ann uses it's internal pager to display articles, but you can choose another program for this. [Default is internal] SCREENSW: If you set this to YES, and ann uses an own screen, ann issues a WBenchToFront()-call before, and a ScreenToFront()-call after every external program. This is usefull for programs using I/O from Workbench. [Defaut is no] NOACTIVE: "Yes" tells ann not to search for an active-file. BE WARNED: ann is going to be VERY SLOW if you set this. If you are using DillonUUCP, use FixActive instead. (See FixActive.doc !) [default is yes at DUUCP, no otherwise] IGNOREACTIVE: Don't search for new groups arrived at you system in the active-file (or UULIB:Newsgroups). [default is no] COLUMNS: At article-presentation, every line contains (in that order) <SelectKey> <Lines> <Subject> <Author> <Date>. The position of (almost) every entry can be varyized by using COLUMNS, values are left edge in percent, while SelectKey is 0 by default. [Default is "3 7 45 75"] EXTERNALPRG: Is the program to be called by pressing E/e in the Pager (article presentation), where every %s is substituted by the actual article-name (including full path). DISPLAYFLAGS: specifies the (only) headerlines to be printed to the & screen in non-verbose mode (see VERBOSE or -v), while HILIGHTFLAGS: specifies the headerlines to be highlighted. (There is no correlation between them, you can hilight lines while simultaneously suppresing them by displayflags). The flags have the following meanings: A,a : Approved C,c : Control D : Date d : Distribution E,e : Expires F : From f : Followup-To K,k : Keywords L,l : Lines M,m : Message-ID N,n : Newsgroups O,o : Organization P,p : Path r : References R : Reply-To S : Subject s : Summary X : Every unregognized header. Default is DFfLRS for Display- and fRS for HilightFlags. See also Verbose Note: This flags are supported only by the internal pager) Verbose: This flag (or the Option -v) defaults the pager to verbose-mode displaying the *complete* header of an article. Toggled by 'v' in pager [Default is no]. FQDN: (FQDN stands for ╗Fully Qualified Domain Names╗) if set to 'N', ann sets the Path: to $nodeid!$userid; by default it sets it to $nodeid.do.main!$userid. See discussion below. This Flag is only supported by AUCPP, DillonUUCP does it's Path-Handling on it's own, while CNEWS uses NewsCtl:whoami). I reccomend everybody using FullyQualifiedDomainNames in the Path-Header, but to disable articles being sent back to you from your feed, you have to contact the postmaster at your feed. If he's running CNews, he only have to set his sys-file to yourname/yourname.do.main:... ; dunno 'bout Bnews RequireLines: if set and Ann doesn't find a Lines:-Header, it marks this by setting Lines to '-'. By default ann counts the lines by itself in this case. You probably don't want to set this flag: you pay for a small speedup by less information. Threaded: Switches Ann into "threaded" mode. This mode consumes more memory, so it is switched off by default. In this mode, the References:-line is interpreted, so follow-ups are to be read directly after the article which was "follow-up"'d. UserShell: The new System()-call of KS/WB 2.0 has a new feature to call either the buildin system-shell or a user-shell. if your preferred shell is fully compatible to the buildin (like WShell), you can set this. SentMail: Where to save copies of outgoing mail to. [no copy] SentNews: Where to save copies of outgoing news to. [no copy] AnnHeader: A filename of a file containing additional headers you want ann to include in the header. Please request RFC1036 before trying to disturb the complete news-system... Killfile: Filename of the global .killfile . Format of killfile is described in section 3.5 of this manual. If you don't set this variable, killing is disabled. ParentPri: The task priority increment of the main program (ann). See SetTaskPri in your dos-manual for useful values. ChildPri: the task priority increment of the child program. -1 is suggested if you are using the .killfile-feature (0 is default, though). 3.4.2: Consult your UUCP documentation, for DUUCP, see UUMAN:Assigns 3.4.3: $UserName is your user-identification. If you don't know what a userid is, you may want to read UUMAN:how2usenet first. $RealName is your "real" name, aka fullname (first and lastname), $HOME is a directory for everything which needs an home :-) Your .annrc and/or .signature might stay there. $TZNAME is the *Name* of your TimeZone, e.g. "GMT" "MESZ", "CST DST". (not really used currently). $TZOFFS is the offset of your timezone relatively to GMT. Must have exactly 5 digits: a sign , two digits for the hour-offset and two digits for the minute-offset. The offset is positive for timezones in the east to Greenwich, negative to timezones in the west. The central european time (CET) is one hour before GMT, so TZOFFS is "+0100", CDT is 6 hours past GMT, so TZOFFS is "-0600". 3.5: Format of .killfile The .killfile constists of a list of lines each containing one killfile-command. Every command is either '-' for disselecting, or '+' for selecting, followed by the key (e.g. Subject: ), followed by the actual pattern. The pattern follows the dos-conventions, so see your dos-manual for details. The following keys are allowed to the time of this writing: Subject:, From:, Date:, Lines:, and additionally References: and Message-Id: if you have enabled "Threaded"-Mode (see above). A word of caution: currently the killfile-algorhithm is VERY SLOW. I do not suggest using the killfile-feature with an unaccelerated (aka plain MC68000 CPU) amiga. Even with an 25MHz MC68030 I think killing is slow. I suggest using "ChildPri -1" if you want to enable the killfile-option. Please note that the pattern.library is ⌐ by Angela Schmitt. 4.0 Runing 4.1 Start You start ann by typing "ann" into the shell. You can append your preferred options (see 1.1) to this command. 4.2 Running Ann distinguishes between three states: i) group-selection ii) article-selection iii) article-presentation (or pager for short) 4.2.1 groupselection \ 4.2.2 article-selection \ All these descriptions are not completed 4.2.3 article-slection > yet. Sorry. But you might find the ? or 4.2.3.1 internal pager / HELP-key to be usefull. 4.2.3.2 external pager / 4.3 Stop You can stop ann by different ways: in each state, ann allows you to stop reading with or without updating your .newsrc. in article-selection it is ^X to stop immediately without updating, and ^Q to stop with updating; in group-selection, and article presentation (pager) it is X for stop without, and Q with updating. You can also send a break-signal to ann. (i.e. by typing the following command(s) in your shell: "break `status COM ann`" for 2.0, or "status" <remembering which cli-num> and "break <remembered cli-num>" 5 Discussion 5.1 Ann uses much memory, but if you have plenty of it and ann is still complaining 'bout not enough memory, there is often one reason: a corrupt active-file! In the active-file, there is a "min" and a "max"-field. ann expects EVERY article between "min" and "max" to be present at your site. While "max" is seldom wrong, the "min"-field is often causing troubles; two kinds of troubles are known: o CNEWS doesn't update the "min"-field at all. This causes ann to allocate much too much memory - even *my* system hasn't that much memory :-) Use fixactive for that. (See FixActive.doc) o Sometimes expire doesn't delete an article (due to various reasons). This causes FixActive to not update the "min"-field (since the article is stell there). This also causes ann to need too much memory. You can find such articles by either using a directory-utility (well, that's real hard work), or using a unix-compatible find-command (SkSh's find is usable). In this case you can enter ╗find "UUNEWS:" -type f -older <date of last month> -exec "delete %s"½ or something like this (see documentation of find). 5.2 Due to the fact ann launches a second process for scanning, you can read a group while a second is scanned. But if you want to g)oto to a specific group, ann might have to wait for the second task to unlock that group. This can take quite some time [the more UNread articles, the longer it takes, so I really reccomend to mark articles you are not interessted in as read (by setting them in "never-read" state)!] So I strongly discourage using g)oto FORWARD early in progress. Even a shutdown and restart using "-g" might be faster! You might want to place groups you often find interessting early in your .newsrc, or using the "-g"-Option at startup. 6 Bugs & Wishes 6.1 If you find bugs, please feel free to send a description to bugs@chumly.ka.sub.org . But PLEASE make SURE that the problem was caused by ann!!! I often get bug-reports which in fact were caused by completely independant programs or wrong set-ups. If you are almost sure the problem was caused by ann, feel free to send me a bug-report. The more precise, the more usefull. Please include at least your news-system, and everything you think it could be of any interesst to me. But please also reduce you report to the real interessting part: if a config-entry doesn't work right, I need that entry, BUT NOT the COMPLETE config-file. If a line in the active-file is of any interesst, send me THAT line (or 3 lines above and below), BUT NOT the COMPLETE active-file. Got it ? [I am afraid of that day someone send me his complete history :-) :-( ] 6.3 If you have an idea how to improve Ann (and this idea is not already mentioned in the wish-list above), you can send it to wishes@chumly