home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / qqp124.zip / QQLINK.DOC next >
Text File  |  1994-04-03  |  22KB  |  498 lines
  1.  
  2.          #####   #####
  3.         ##     ## ##     ##
  4.             ##   ## ##   ## ##    ###### ##   ## ##  ##  V1.24
  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 to some of
  114. the more common ones, run QQLink 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. -pt or /LINKPASS
  226.         : Link passthru areas if asked to. Without this switch, attempts
  227.         to link passthru areas will be ignored. This was the default
  228.         behaviour of QQLink v1.22 and below (oops).
  229.  
  230. -S or /SLOW
  231.         : Link slowly, without creating a .QQL file. If you have a very
  232.         large number of areas, some of which receive very little
  233.         traffic, slow linking can save you space by decreasing the
  234.         number of .QQL files QQLink needs to maintain. Slow linking is
  235.         only marginally faster than other linkers (ie. much slower than
  236.         QQLink's normal pace).
  237.  
  238. -s  or /SUBJ
  239.         : Selects ("Old-style") linking with subjectlines, rather than
  240.         the FTS-0009 MSGID and REPLY kludges. Although this linking
  241.         scheme has its problems, and does not use the Squish format to
  242.         its greatest potential, in areas where the kludges are not
  243.         widely supported in others' software, there may be nothing else
  244.         for it.
  245.  
  246.         Because of its "incremental linking" features, QQLink is still
  247.         significantly faster than Squish at subjectline linking.
  248.  
  249. -m  or /MIXED
  250.         : Selects "Mixed mode" linking with both MSGID/REPLY and subject
  251.         lines. This method is a "best of both worlds" that attempts to
  252.         link messages with MSGIDs according to FTS9, and "guesses" via
  253.         subject lines at the most appropriate original message for all
  254.         others.
  255.  
  256.         I've had extremely varying results with this... it seems to work
  257.         very well in areas with simple threads, and comparatively few
  258.         FTS9 compliant messages. However, with complex threads involving a
  259.         roughly equal proportion of FTS9 and non-FTS9 messages, it
  260.         merely added to the confusion. Your mileage may vary.
  261.  
  262.         I think everyone who's commented on previous versions of QQLink
  263.         has asked for a feature like this; so here it is! The only
  264.         trade-off is that use of the mixed mode linking scheme doubles
  265.         the length of .QQL files to slightly less than 16K.
  266.  
  267. -t<name>  or /TOALL:<name>
  268.         : Selects a to-name that will be assumed to indicate that a
  269.         message is not a reply (such as "ALL"). Messages addressed to the
  270.         specified name will not be linked to an earlier message, unless
  271.         they have an explicit REPLY kludge (in mixed mode). This feature
  272.         is turned off by default. The /TOALL switch has no effect in FTS9
  273.         linking mode.
  274.  
  275. -T<number> or /TRUNC:<number>
  276.         : Truncates subject lines to <number> characters before linking
  277.         in mixed or subjectline mode. This is handy where you often
  278.         receive messages from people with "Fido Ignorant" message
  279.         editors which truncate subject lines (eg. SLMR).
  280.  
  281.         ---{ 5 }-----{ Advanced Techniques }------
  282.  
  283. 1)      Using different linking methods for different areas.
  284.  
  285.         If you carry a number of varied areas, or subscribe to an
  286.         Othernet (as I do) where FTS9 identification for messages is not
  287.         widely used, you might want to link some areas with FTS9 style
  288.         linking, and some with subjectline linking. You might even, (God
  289.         forbid!) want to link some areas with QQLink, and some with some
  290.         other software.
  291.  
  292.         This is now possible, through the use of the /XLOG: (-x) and
  293.         /OUT: (-o) commandline parameters. For example, suppose I want
  294.         to link the areas LINK, BBSCMNTS, and OCCULT with subjectline
  295.         linking, and all others with FTS9: I could create a file called
  296.         SUBJLINK.LOG, and run QQLink as follows
  297.  
  298.         QQLink -fechotoss.log -xsubjlink.log -olinkdone.log
  299.         QQLink /SUBJ -fechotoss.log /KILL -xlinkdone.log
  300.         ...
  301.         DEL echotoss.log
  302.  
  303.         The first invocation of QQLink links (using MSGID/REPLY) those
  304.         areas specified (by Squish) in echotoss.log, excluding those in
  305.         SUBJLINK.LOG. The list of areas linked is output to
  306.         LINKDONE.LOG. The second run links the remaining areas (those in
  307.         ECHOTOSS but not LINKDONE) by subjectline, and deletes
  308.         LINKDONE.LOG when it's finished.
  309.  
  310.         Using this method to link some third set of areas with /MIXED
  311.         mode, or with another reply linker altogether are left as an
  312.         exercise for the reader.
  313.  
  314.  
  315. 2)      Running multiple reply linkers.
  316.  
  317.         A couple of correspondents have alerted me to the fact that, as
  318.         QQLink does not delete old reply links in a Squish messagebase
  319.         it's possible (though very slow) to run "Squish LINK" over
  320.         areas, and then follow up by linking with QQLink, thereby
  321.         gaining some of the advantages of FTS9 style linking, while not
  322.         leaving MSGID-less messages unlinked.
  323.  
  324.         Of course, QQLink now has /MIXED mode which accomplishes the
  325.         same effect much, much faster.
  326.  
  327.         You might want to try running some other kind of linker (are
  328.         there any? EIDs perhaps?) with QQLink going over the top... If
  329.         it just makes a mess, you can delete the messed up links by
  330.         running QQLink over the area with the /CLEAN /RELINK parameters.
  331.  
  332.  
  333. 3)      Running QQLink under OS/2.
  334.  
  335.         Ralf Brandt of 2:2410/104.3 has sent me a binary and source diff
  336.         for his OS/2 port of QQLink, which compiles under IBM's Cset
  337.         compiler. I don't run OS/2, and *can't* answer for the binary,
  338.         but it's requestable from 3:771/340 as QQLINKP
  339.  
  340.         Source is also available - the magic name is QQLSRC You can create
  341.         a DOS executable with any of Borland's C compilers; Watcom and MSC
  342.         ports shouldn't be hard. GCC ports are only for the fearless.
  343.  
  344.  
  345. 4)      Linking your NETMAIL area.
  346.  
  347.         QQLink treats the Netmail area specified in Squish.CFG as just
  348.         another echomail messagebase. You can cause QQLink to link it by
  349.         specifying the "name" of your netmail area on the commandline,
  350.         or in an EchoToss.LOG file specified with the -f or /LOG:
  351.         parameter.
  352.  
  353.         I just run QQLink as
  354.  
  355.         QQLink -fechotoss.log NETMAIL
  356.  
  357.         each time it runs - if NETMAIL has no new messages, QQLink takes
  358.         a mere fraction of a second to open and close it.
  359.  
  360.  
  361. 5)      Using the "QQLINK=" environment string
  362.  
  363.         You can specify any commandline parameters on a "QQLINK" DOS
  364.         environment string. The environment string is processed before
  365.         (ie "to the left of") the real command line for purposes of the
  366.         /LOG, /XLOG, /KILL and /NOKILL switches.
  367.  
  368.         As an example, my AutoExec.BAT contains the following line:
  369.  
  370.         set QQLINK=/CFG:c:\squish\squish.CFG -uGggCW
  371.  
  372.  
  373. 6)      Full screen configuration utility.
  374.  
  375.         Just kidding :)
  376.  
  377.  
  378.         ---{ 6 }---------{ Why QQLink? }----------
  379.  
  380. At the moment I am aware of two other products that do the same job as
  381. QQLink - Squish itself, and David Nugent's SQLink programme. I've
  382. already discussed the shortcomings of Squish's linker, primarily lack of
  383. support for FTS-0009.
  384.  
  385. I ran SQLink for most of the time since I started my Maximus BBS, until
  386. I developed QQLink to overcome certain problems with SQLink, mainly its
  387. godawful slowness when linking large areas. This is mainly because
  388. SQLink will relink and scan all the messages in an area, as it has no
  389. way of knowing a) where it left off last time, or b) what the MSGIDs of
  390. all those already linked messages are.
  391.  
  392. QQLink gets around this by storing this information in a ".QQL" file,
  393. either called <AREA>.QQL for a Squish base, or <AREA>\QQLINK. for a
  394. *.MSG base, where <AREA> is the name of the area. For example, the
  395. Squish area \MAIL\NET would consist of: \MAIL\NET.SQD, \MAIL\NET.SQI,
  396. \MAIL\NET.QQL, and so on.
  397.  
  398. These .QQL files are usually much smaller (8K) than the rest of the
  399. area, so you won't be losing much space. The gain is tremendous - If you
  400. receive 20 new messages in an area where you keep 500, QQLink will link
  401. only the new 50, as opposed to SQLink's working on all 500. In these
  402. circumstances, QQLink would take just 4% of the time SQLink took. For
  403. smaller areas, such as when used on a point, QQLink will still be around
  404. 10 times as fast as SQLink, doing the same job.
  405.  
  406.  
  407.         ---{ 7 }-----{ Changes since v1.00 }------
  408.  
  409. v1.01:  Fixed miscellaneous anomalies in config file parser.
  410.  
  411. v1.10:  Added subject linking and XLOGs.
  412.  
  413. v1.20:  Added mixed linking, outlogs, "clean linking", pretty colours,
  414.         environment string, caching of message headers, changed memory
  415.         model.
  416.  
  417. v1.21:  Fixed commandline parsing bug, added $<path> and *<path>
  418.         parameters. Kludged subject & mixed linking to work better...
  419.  
  420. v1.22:  Fixed a variety of bugs, attempted to fix reported bugs that I
  421.         couldn't get to happen myself. OS/2 version should be coming
  422.         soon!
  423.  
  424. v1.23:  Not generally released.
  425.  
  426. v1.24:  Passthru areas will now not be linked by default. QQLink should
  427.         deal better with *.MSG areas. Subject lines will be "massaged"
  428.         before linking: converted to lower case, "re:" stripped, optionally
  429.         truncated.
  430.  
  431. v1.24B: Source code merged with Ralf Brandt's OS/2 port.
  432.  
  433.         ---{ 8 }------------{ Cost }--------------
  434.  
  435. Like Squish itself, QQLink is FREEWARE. I retain copyright, but grant
  436. anyone who wishes to the right to use and distribute it, provided:
  437.  
  438.         No charge is levied for copying QQLink above and beyond the
  439.         actual costs of disks or other media, or subscription to a BBS
  440.         from which QQLink is downloaded.
  441.  
  442.         This file, QQLink.DOC, and the accompanying executables are not
  443.         modified in any way, except to place them in a compressed or
  444.         archived format.
  445.  
  446. Of course, QQLink carries no implicit or explicit warranty. I can only
  447. guarantee that it will take up your disk space.
  448.  
  449. If you admire QQLink or use it regularly please send a postcard to the
  450. snailmail address below - I welcome feedback and would like to see how
  451. far around the world QQLink progresses, if it does.
  452.  
  453. If you regularly use QQLink in a commercial environment, add a bar of
  454. chocolate to the postcard. 8-)
  455.  
  456.  
  457.         ---{ 9 }-----{ Reaching the Author }------
  458.  
  459. I can be reached at any of the following addresses:
  460.  
  461. FidoNet:
  462.         Josh Parsons    at 3:771/340
  463.  
  464.     If you have a simple question about QQLink, you might post it in
  465.     TUB, as there are other people there who may be able to help.
  466.  
  467. SnailMail: (ie. post)
  468.  
  469.         Josh Parsons
  470.         42 Glen Rd
  471.         Kelburn
  472.         Wellington 6005
  473.         New Zealand
  474.  
  475.  
  476.         ---{ 10 }-------{ Acknowledgements }-------
  477.  
  478. Thanks to:
  479.         Robert Ruthven for encouraging me.
  480.         Ewen McNeill for providing me with my fidonet feed.
  481.         Scott J. Dudley for writing Squish and the MSGAPI (great stuff).
  482.  
  483.         All the folks in TUB.
  484.  
  485.         USA readers for putting up with my spelling of "colour" and
  486.         "programme".
  487.  
  488. Squish, and Maximus are trademarks of Scott J. Dudley.
  489. Fidonet is a trademark of Tom Jennings.
  490.  
  491.  
  492.  
  493.  
  494.                         Made in New Zealand.  O~~\
  495.                                      / \_/
  496.  
  497.  
  498.