home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR36 / QQL121.ZIP / QQLINK.DOC next >
Text File  |  1993-10-29  |  20KB  |  461 lines
  1.  
  2.          #####   #####
  3.         ##     ## ##     ##
  4.             ##   ## ##   ## ##    ###### ##   ## ##  ##  V1.21
  5.         ##     ## ##     ## ##        ##     ###  ## ## ##
  6.         ## #### ## #### ##        ##     ## # ## ####
  7.          #####   #####  ##        ##     ##  ### ## ##
  8.         ###    ### ##### ###### ##   ## ##  ##
  9.  
  10.              ***  The Documentation  ***
  11.  
  12.  
  13.         ---{ 1 }---------{ Introduction }---------
  14.  
  15. Welcome to QQLink - a reply linker for use with the "Squish" mail
  16. processor by Scott J Dudley. If this doesn't make much sense to you,
  17. might have just downloaded the wrong archive - from here on I'll be
  18. assuming that you run, or are about to set up a Fidonet BBS or point
  19. with Scott's software. If some of this is unfamiliar, read Squish.PRN
  20. first, it's got a good basic explanation of what's going on.
  21.  
  22. QQLink is quite a simple programme - if you haven't already, go and set
  23. up the rest of your mail software. Things will tick along quite happily
  24. without it (not that you won't notice the lack!).
  25.  
  26.  
  27.         ---{ 2 }---{ What QQLink does for you }---
  28.  
  29. One of the problems with Fidonet echomail, and similar media such as
  30. Usenet's news is that of threading - jumping forward to a message's
  31. reply/replies, back to its original, between replies to the same
  32. message etc. Unlike a local BBS message area, message numbers, and even
  33. the order of messages may vary, so some tricky method must be used,
  34. first to uniquely identify messages in a way that does not vary from
  35. system to system, and secondly to use this information to encode the
  36. structure of a reply thread into message packets.
  37.  
  38. In Fidonet, this is accomplished by the use of hidden "kludges", called
  39. MSGID and REPLY. These are defined in the standards document "FTS-0009".
  40. Formerly, it was common practice to build the reply links by guessing
  41. from the subject lines of messages - ie. if a message has the subject
  42. "Re: Wibbling and widgets", then the next message with the same subject
  43. becomes its reply.
  44.  
  45. Needless to say, this has some disadvantages, but this is what Squish
  46. will do! For example, often a thread of discussion will split into two
  47. or more subthreads on different topics, but with the same subject line.
  48. Using Squish's builtin reply linking, all the messages in both threads
  49. will become jumbled into one. Also, in situations where a user will not,
  50. or cannot quote others, attempting to find what they were replying to
  51. could become a nightmare.
  52.  
  53. QQLink solves all this, and additionally, almost always links faster than
  54. Squish (QQLink stands for Quick sQuish Linker).
  55.  
  56. The speed factor is gained by storing link information in an additional
  57. 8K file for each area linked. This is a very good tradeoff - most
  58. echomail areas take up considerably than this, so an additional 8K is
  59. negligible - Squish takes the same approach to storing its
  60. dupe-database. 
  61.  
  62.         ---{ 3 }------{ How you use QQLink }------
  63.  
  64. Simply drop QQLINK.EXE into whatever directory you keep Squish in. You
  65. can test it out by manually linking an area. If your Squish.CFG file is
  66. in the current directory, simply enter
  67.  
  68. QQLink TUB
  69.  
  70. Or QQLink <some area on your system> if you don't receive the TUB echo.
  71. QQLink will automatically read the path to the echo you specify, and its
  72. type (Squish or *.MSG) from your Squish.CFG or AREAS.BBS. You'll see a
  73. progress report as the area is linked, and a final report on the number
  74. of messages linked in this pass, with the percentage of messages in the
  75. area that have FTS-9 kludge lines. If this percentage is below about 70%,
  76. you should consider using a different link mode, /SUBJ or /MIXED (see
  77. below).
  78.  
  79. If you have a Squish configuration file called something other than
  80. Squish.CFG, you can specify it using the -c command line switch (see
  81. below)
  82.  
  83. This manual linking isn't going to be much use if you receive multiple
  84. megabytes a day, however. So the best thing to do is add a call to
  85. QQLink to the batch file you use to process inbound echomail packets.
  86. Make sure Squish is generating an EchoToss.LOG file - the following
  87. should suffice:
  88.  
  89. change  Squish IN OUT
  90. to      Squish IN OUT -fechotoss.LOG
  91.  
  92. if you are using Squish in multipass mode, or doing any other stuff,
  93. consult your Squish.PRN.
  94.  
  95. After the call to Squish in your batch file, enter the following:
  96.  
  97. QQLink -fechotoss.LOG
  98. DEL echotoss.LOG
  99.  
  100. If you have other programmes using EchoToss.LOG, make sure they go in
  101. *before* the DEL! QQLink will now run automatically to link any incoming
  102. messages - messages posted by you are assumed to be linked by your BBS
  103. or editor software (this is true for Maximus, Pobble, and all editors
  104. I'm aware of that use the Squish format).
  105.  
  106. Use of a disk cache with all mail processing software is STRONGLY
  107. recommended.
  108.  
  109.  
  110.     ---{ 4 }---{ Command line parameters }----
  111.  
  112. QQLink now accepts a wide variety of command line parameters: here's a
  113. description of each, in gory detail (for a quick reference, run QQLink
  114. with the /HELP or -? parameter).
  115.  
  116. $<pathname of a Squish style messagebase> or
  117. *<pathname of a *.MSG style messagebase>
  118.         : Links the messagebase specified, even if it is not listed in
  119.         your Squish.CFG file. This might be useful if you use multiple
  120.         netmail areas with a utility like NetMgr, or if you wish to link
  121.         some local areas for some reason.
  122.  
  123. -c<filename> or /CFG:<filename>
  124.         : Sets the path to your Squish configuration file to be
  125.         <filename>. QQLink reads a lot of important information from
  126.         Squish.CFG, including the paths, tagnames, and formats of all
  127.         your areas, and the path to your AREAS.BBS if you have one.
  128.  
  129. -a<filename> or /AREAS:<filename>
  130.         : Sets the path and filename of an AREAS.BBS format file to be
  131.         read in addition to or instead of a Squish.CFG configuration
  132.         file. This switch overrides the "AreasBBS" configuration verb in
  133.         Squish.CFG. You could use it to run QQLink with a *.SQ? or *.MSG
  134.         format mail processor other than Squish (QMail or IMail for
  135.         example).
  136.  
  137. -f<echotoss> or /LOG:<echotoss>
  138.         : Specifies a file containing a list of area tags, seperated by
  139.         carriage return/line feed pairs - the areas specified will be
  140.         linked in this run of QQLink.
  141.  
  142. -x<echotoss> or /XLOG:<echotoss>
  143.         : Specifies a file containing a list of area tags, seperated by
  144.         carriage return/line feed pairs - the areas specified will be
  145.         excluded from linking in this run of QQLink.
  146.  
  147.         The /LOG and /XLOG parameters are parsed in left to right order
  148.         in the command line, so "QQLink -flog1.log -xlog1.log" will link
  149.         no areas, but "QQLink -xlog1.log -flog1.log" will link every
  150.         area specified in LOG1.LOG
  151.  
  152.         Multiple log parameters may be used: "QQLink -flog1.log
  153.         -xlog2.log -xlog3.log -flog4.log" will link all those areas
  154.         specified in LOG1, EXCEPT those that are found in either LOG2 or
  155.         LOG3, AND the areas in LOG4, regardless of whether they are also
  156.         in LOG2 and LOG3.
  157.  
  158. -o<echotoss> or /OUT:<echotoss>
  159.         : Specifies an EchoToss.LOG format file to write the names of
  160.         the areas actually linked to. If the file you name already
  161.         exists, it will be appended to.
  162.  
  163. -k  or /KILL and -k- or /NOKILL
  164.         : These switches turn on and off deletion of the EchoToss.LOG
  165.         files referenced by the /LOG and /XLOG switches, in case you are
  166.         averse to using the DEL command for some reason. The default is
  167.         off, and the command line is parsed from left to right, so
  168.         "QQLink -k -fLOG1 -k- -xLOG2" will, when QQLink finishes
  169.         linking, delete LOG1, but not LOG2.
  170.  
  171. -u[parms] or /UGLY[:parms] controls use of screen colours.
  172.         : This switch allows you to control QQLink's use of colour, via
  173.         ANSI codes. By default, if you have ANSI.SYS or an equivalent
  174.         driver installed, QQLink will display its output in pretty
  175.         colours. To supress this, you may specify the -u or /UGLY
  176.         switches with no additional argument.
  177.  
  178.         You may also customize QQLink's use of colour, by specifying a
  179.         5-character argument to these parameters, of the form "TLSHE"
  180.         where   T = the "Title" colour
  181.                 L = the "Linking" colour
  182.                 S = the "Summary" colour
  183.                 H = the "Help" colour
  184.                 E = the "Error" colour
  185.  
  186.         Each of these characters can be one of K,R,G,B,Y,C,M,W,D, which
  187.         represent black (K), the primary colours (Red, Green, and Blue),
  188.         the secondary colours (Yellow, Cyan, Magenta), White, and
  189.         Default. If the character used is uppercase, a bright colour
  190.         will be displayed, if lowercase, a dim colour.
  191.  
  192.         Examples:       QQLink -uRWBdd          (a patriotic scheme)
  193.                         QQLink /UGLY:RrRyB      (a socialist one)
  194.  
  195. -r  or /RELINK
  196.         : Relinks *every* message in the areas linked, re-creating the
  197.         .QQL link information file from scratch. This could be useful if
  198.         your .QQL file became corrupted somehow, or you wanted to
  199.         benchmark QQLink's straight linking speed.
  200.  
  201.         QQLink may need to relink your areas should you change linking
  202.         methods, or upgrade to a newer version, but it can detect these
  203.         conditions for itself; method and version information is stored
  204.         in the .QQL file.
  205.  
  206. -n  or /CLEAN
  207.         : Removes any old reply linking information from each message
  208.         linked (by default, the old links will be merged with the new).
  209.         In the normal course of operation, this will not make any
  210.         difference, as new messages arriving on your system have no link
  211.         information, but it will make a difference if you use some other
  212.         linker, or are /RELINKing the area.
  213.  
  214.         You might want to use the /RELINK /CLEAN combination if some
  215.         buggy software has damaged the reply links in your area. /CLEAN
  216.         will also be useful if you want to change an area from being
  217.         solely subjectline linked to being solely FTS-9 linked, removing
  218.         any old subjectline linkages before linking the area.
  219.  
  220. -l  or /ALL
  221.         : Links every area on your system (including netmail areas).
  222.         This switch is exactly equivalent to listing every area in your
  223.         configuration files on the QQLink command line.
  224.  
  225. -s  or /SUBJ
  226.         : Selects ("Old-style") linking with subjectlines, rather than
  227.         the FTS-0009 MSGID and REPLY kludges. Although this linking
  228.         scheme has its problems, and does not use the Squish format to
  229.         its greatest potential, in areas where the kludges are not
  230.         widely supported in others' software, there may be nothing else
  231.         for it.
  232.  
  233.         Because of its "incremental linking" features, QQLink is still
  234.         significantly faster than Squish at subjectline linking.
  235.  
  236. -m  or /MIXED
  237.         : Selects "Mixed mode" linking with both MSGID/REPLY and subject
  238.         lines. This method is a "best of both worlds" that attempts to
  239.         link messages with MSGIDs according to FTS9, and "guesses" via
  240.         subject lines at the most appropriate original message for all
  241.         others.
  242.  
  243.         I've had extremely varying results with this... it seems to work
  244.         very well in areas with simple threads, and comparatively few
  245.         FTS9 compliant messages. However, with complex threads involving a
  246.         roughly equal proportion of FTS9 and non-FTS9 messages, it
  247.         merely added to the confusion. Your mileage may vary.
  248.  
  249.         I think everyone who's commented on previous versions of QQLink
  250.         has asked for a feature like this; so here it is! The only
  251.         trade-off is that use of the mixed mode linking scheme doubles
  252.         the length of .QQL files to slightly less than 16K.
  253.  
  254. -t<name>  or /TOALL:<name>
  255.         : Selects a to-name that will be assumed to indicate that a
  256.         message is not a reply. By default this is "ALL". Messages
  257.         addressed to the specified name will not be linked to an earlier
  258.         message, unless they have an explicit REPLY kludge (in mixed
  259.         mode). If you do not specify any <name> parameter, all messages
  260.         will be linked, regardless of what to-name they have. This
  261.         switch has no effect in FTS9 linking mode.
  262.  
  263.  
  264.         ---{ 5 }-----{ Advanced Techniques }------
  265.  
  266. 1)      Using different linking methods for different areas.
  267.  
  268.         If you carry a number of varied areas, or subscribe to an
  269.         Othernet (as I do) where FTS9 identification for messages is not
  270.         widely used, you might want to link some areas with FTS9 style
  271.         linking, and some with subjectline linking. You might even, (God
  272.         forbid!) want to link some areas with QQLink, and some with some
  273.         other software.
  274.  
  275.         This is now possible, through the use of the /XLOG: (-x) and
  276.         /OUT: (-o) commandline parameters. For example, suppose I want
  277.         to link the areas LINK, BBSCMNTS, and OCCULT with subjectline
  278.         linking, and all others with FTS9: I could create a file called
  279.         SUBJLINK.LOG, and run QQLink as follows
  280.  
  281.         QQLink -fechotoss.log -xsubjlink.log -olinkdone.log
  282.         QQLink /SUBJ -fechotoss.log /KILL -xlinkdone.log
  283.         ...
  284.         DEL echotoss.log
  285.  
  286.         The first invocation of QQLink links (using MSGID/REPLY) those
  287.         areas specified (by Squish) in echotoss.log, excluding those in
  288.         SUBJLINK.LOG. The list of areas linked is output to
  289.         LINKDONE.LOG. The second run links the remaining areas (those in
  290.         ECHOTOSS but not LINKDONE) by subjectline, and deletes
  291.         LINKDONE.LOG when it's finished.
  292.  
  293.         Using this method to link some third set of areas with /MIXED
  294.         mode, or with another reply linker altogether are left as an
  295.         exercise for the reader.
  296.  
  297.  
  298. 2)      Running multiple reply linkers.
  299.  
  300.         A couple of correspondents have alerted me to the fact that, as
  301.         QQLink does not delete old reply links in a Squish messagebase
  302.         it's possible (though very slow) to run "Squish LINK" over
  303.         areas, and then follow up by linking with QQLink, thereby
  304.         gaining some of the advantages of FTS9 style linking, while not
  305.         leaving MSGID-less messages unlinked.
  306.  
  307.         Of course, QQLink now has /MIXED mode which accomplishes the
  308.         same effect much, much faster.
  309.  
  310.         You might want to try running some other kind of linker (are
  311.         there any? EIDs perhaps?) with QQLink going over the top... If
  312.         it just makes a mess, you can delete the messed up links by
  313.         running QQLink over the area with the /CLEAN /RELINK parameters.
  314.  
  315.  
  316. 3)      Running QQLink under OS/2.
  317.  
  318.         There is still no stable OS/2 port of QQLink to OS/2 :( The
  319.         source code is available to volunteers... (You'll need a copy of
  320.         the Squish MSGAPI, and a compiler that can compile it).
  321.  
  322.  
  323. 4)      Linking your NETMAIL area.
  324.  
  325.         QQLink treats the Netmail area specified in Squish.CFG as just
  326.         another echomail messagebase. You can cause QQLink to link it by
  327.         specifying the "name" of your netmail area on the commandline,
  328.         or in an EchoToss.LOG file specified with the -f or /LOG:
  329.         parameter.
  330.  
  331.         I just run QQLink as
  332.  
  333.         QQLink -fechotoss.log NETMAIL
  334.  
  335.         each time it runs - if NETMAIL has no new messages, QQLink takes
  336.         just a fraction of a second to open and close it.
  337.  
  338.  
  339. 5)      Using the "QQLINK=" environment string
  340.  
  341.         You can specify any commandline parameters on a "QQLINK" DOS
  342.         environment string. The environment string is processed before
  343.         (ie "to the left of") the real command line for purposes of the
  344.         /LOG, /XLOG, /KILL and /NOKILL switches.
  345.  
  346.         As an example, my AutoExec.BAT contains the following line:
  347.  
  348.         set QQLINK=/CFG:c:\squish\squish.CFG -uGggCW
  349.  
  350.  
  351. 6)      Full screen configuration utility.
  352.  
  353.         Just kidding :)
  354.  
  355.  
  356.         ---{ 6 }---------{ Why QQLink? }----------
  357.  
  358. At the moment I am aware of two other products that do the same job as
  359. QQLink - Squish itself, and David Nugent's SQLink programme. I've
  360. already discussed the shortcomings of Squish's linker, primarily lack of
  361. support for FTS-0009.
  362.  
  363. I ran SQLink for most of the time since I started my Maximus BBS, until
  364. I developed QQLink to overcome certain problems with SQLink, mainly its
  365. godawful slowness when linking large areas. This is mainly because
  366. SQLink will relink and scan all the messages in an area, as it has no
  367. way of knowing a) where it left off last time, or b) what the MSGIDs of
  368. all those already linked messages are.
  369.  
  370. QQLink gets around this by storing this information in a ".QQL" file,
  371. either called <AREA>.QQL for a Squish base, or <AREA>\QQLINK. for a
  372. *.MSG base, where <AREA> is the name of the area. For example, the
  373. Squish area \MAIL\NET would consist of: \MAIL\NET.SQD, \MAIL\NET.SQI,
  374. \MAIL\NET.QQL, and so on.
  375.  
  376. These .QQL files are usually much smaller (8K) than the rest of the
  377. area, so you won't be losing much space. The gain is tremendous - If you
  378. receive 20 new messages in an area where you keep 500, QQLink will link
  379. only the new 50, as opposed to SQLink's working on all 500. In these
  380. circumstances, QQLink would take just 4% of the time SQLink took. For
  381. smaller areas, such as when used on a point, QQLink will still be around
  382. 10 times as fast as SQLink, doing the same job.
  383.  
  384.  
  385.         ---{ 7 }-----{ Changes since v1.00 }------
  386.  
  387. v1.01:  Fixed miscellaneous anomalies in config file parser.
  388.  
  389. v1.10:  Added subject linking and XLOGs.
  390.  
  391. v1.20:  Added mixed linking, outlogs, "clean linking", pretty colours,
  392.         environment string, caching of message headers, changed memory
  393.         model.
  394.  
  395. v1.21:  Fixed commandline parsing bug, added $<path> and *<path>
  396.         parameters. Kludged subject & mixed linking to work better...
  397.  
  398.  
  399.         ---{ 8 }------------{ Cost }--------------
  400.  
  401. Like Squish itself, QQLink is FREEWARE. I retain copyright, but grant
  402. anyone who wishes to the right to use and distribute it, provided:
  403.  
  404.         No charge is levied for copying QQLink above and beyond the
  405.         actual costs of disks or other media, or subscription to a BBS
  406.         from which QQLink is downloaded.
  407.  
  408.         This file, QQLink.DOC, and the accompanying executables are not
  409.         modified in any way, except to place them in a compressed or
  410.         archived format.
  411.  
  412. Of course, QQLink carries no implicit or explicit warranty. I can only
  413. guarantee that it will take up your disk space.
  414.  
  415. If you admire QQLink or use it regularly please send a postcard to the
  416. snailmail address below - I welcome feedback and would like to see how
  417. far around the world QQLink progresses, if it does.
  418.  
  419. If you regularly use QQLink in a commercial environment, add a bar of
  420. chocolate to the postcard. 8-)
  421.  
  422.  
  423.         ---{ 9 }-----{ Reaching the Author }------
  424.  
  425. I can be reached at any of the following addresses:
  426.  
  427. FidoNet:
  428.         Josh Parsons    at 3:771/330.64
  429.  
  430.     If you have a simple question about QQLink, you might post it in
  431.     TUB, as there are other people there who may be able to help.
  432.  
  433. SnailMail: (ie. post)
  434.  
  435.         Josh Parsons
  436.         42 Glen Rd
  437.         Kelburn
  438.         Wellington 6005
  439.         New Zealand
  440.  
  441.  
  442.         ---{ 10 }-------{ Acknowledgements }-------
  443.  
  444. Thanks to:
  445.         Robert Ruthven for encouraging me.
  446.         Scott J. Dudley for his excellent MSGAPI, which I used.
  447.  
  448.         USA readers for putting up with my spelling of "colour" and
  449.         "programme".
  450.  
  451. Squish, and Maximus are trademarks of Scott J. Dudley.
  452. Fidonet is a trademark of Tom Jennings.
  453.  
  454.  
  455.  
  456.  
  457.                         Made in New Zealand.  O~~\
  458.                                      / \_/
  459.  
  460.  
  461.