home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / sqlnk120.zip / SQLink.Doc < prev    next >
Text File  |  1993-04-22  |  16KB  |  417 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.     SQLink Version 1.20
  10.     Squish message base MSGID/REPLY linker
  11.     For MSDOS and OS/2 systems
  12.     ____________________________________________________________
  13.  
  14.  
  15.     David L. Nugent & Unique Computing Pty Ltd.
  16.     Copyright (C) 1992-93
  17.     All Rights Reserved.
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.                            PLEASE NOTE!
  37.  
  38.     In using  the enclosed software  you do so  entirely at your
  39.     own risk. The author and/or distributors are not responsible
  40.     for any  loss or damage as  a result of using  this product,
  41.     consequential or  otherwise, and will not  be liable for any
  42.     circumstances arising out of  its  use and the only function
  43.     that  is  guaranteed  to  work  as  advertised  is that this
  44.     software and/or documentation will occupy disk space.
  45.  
  46.     This  product  is  FREE FOR ANY USE  and may be  distributed
  47.     without  consent for that purpose.  Commercial distribution,
  48.     including  sale  IN ANY  FORM  is  prohibited.
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.     ABOUT SQLINK & REPLY LINKING
  64.     ----------------------------
  65.  
  66.  
  67.     SQLink is  a supplement to Scott  Dudley's Squish conference
  68.     mail  processor. It  is a  direct replacement  of the SQUISH
  69.     LINK  function, and  instead of  using the  more traditional
  70.     reply thread  linking by subject,  SQLink uses "true"  reply
  71.     linking,  taking advantage  of the  fact that  Squish format
  72.     areas can retain up to 10  reply chain links instead of only
  73.     one  as  with  other  formats  used  by  some  other Fidonet
  74.     compatible Bulletin Board and messaging systems.
  75.  
  76.     The  fact  that  a  message  can  be  linked  to its  "true"
  77.     original  makes conversations  in conference  mail easier to
  78.     follow  directly  from  the  original  post  to  its  direct
  79.     descendants (the replies to  the original), replies to those
  80.     individual replies etc. It  can be readily demonstrated that
  81.     any conversation thread is in the form of a tree, thus:
  82.  
  83.  
  84.     Original
  85.     Message A ------ Reply A.1 -->
  86.                 |
  87.                 +--- Reply A.2 ------ Reply A.2.1 -->
  88.                 |                |
  89.                 |                +--- Reply A.2.2 -->
  90.                 |
  91.                 +--- Reply A.3 ------ Reply A.3.1 -->
  92.                 |                |
  93.                 |                +--- Reply A.3.2 -->
  94.                 |                |
  95.                 |                +--- Reply A.3.3 -->
  96.                 V
  97.  
  98.  
  99.     Within a local message  area, Maximus CBCS already maintains
  100.     "true" reply  threads. Second and subsequent  replies to any
  101.     individual message gets added to the existing replies, as it
  102.     should be. However, in  wide area conferencing systems, such
  103.     as  echomail,  this  direct  linkage  information gets lost,
  104.     since any reply linkage information is effectively gone once
  105.     it is scanned and packed for transmission to another system.
  106.  
  107.     The traditional answer  to this was to use  the subject line
  108.     (or part thereof) for reply linkage, so that messages with a
  109.     common subject would  appear to be part of  one linear reply
  110.     chain.   This  requires   that  all   participants  in  that
  111.     particular conversation retain the  same subject (even if it
  112.     is  no  longer  meaningful),  but  does  not  prevent  other
  113.     spinoffs  from  the  same  thread,  or  someone  entering an
  114.     entirely unrelated message using the same subject line, from
  115.     being confused  into the same thread.  So, while this method
  116.     works adequately (sometimes), it's really just a work-around
  117.     invented because it was "better than nothing".
  118.  
  119.  
  120.  
  121.  
  122.     The  problem  in  true  reply  linkage  is  twofold;  first,
  123.     messages must be uniquely identified in a similar way across
  124.     all systems to which it travels. Secondly, when a message is
  125.     a reply, it must retain not only its  own unique identifier,
  126.     but also the indentifier of the original message.
  127.  
  128.     A method  of  doing  this,  now  fairly  widely supported in
  129.     Fidonet technology  software and becoming  more common every
  130.     day, is using two "control"  lines within message text which
  131.     are  normally  hidden  from  view  when  reading.  These are
  132.     ^aMSGID   (message   identifier)   and   ^aREPLY   (reply-to
  133.     identifier).
  134.  
  135.     The usual format is:
  136.  
  137.         ^aMSGID: <origin_address> <8_digit_hex_number>
  138.  
  139.     and
  140.  
  141.         ^aREPLY: <MSGID_string_of_original_message>
  142.  
  143.     Whether this  format is strictly  adhered to or  not, SQLink
  144.     does  not care.  It only  matters that  whatever follows the
  145.     "^aMSGID:" is  completely unique, and  never duplicated (for
  146.     this reason, the  MSGID would be very useful  as a duplicate
  147.     detection scheme once its  use becomes universal). One other
  148.     important  thing about  MSGID lines  is that  they will only
  149.     ever be  added and generated in  messages which originate on
  150.     the local system - almost always  at the time it is created.
  151.     They  will not  be stripped,  changed or  normalised by  any
  152.     systems that the message passes through. (Refer to FTS-9 for
  153.     the full MSGID/REPLY specification document).
  154.  
  155.     In  linking  replies,  SQLink  threads  replies  using these
  156.     special  control  lines  ONLY.   Because  not  all  software
  157.     generates  and  uses  these  lines,  the  scheme  is not yet
  158.     perfect, but  in most cases  it will certainly  be adequate.
  159.     Unfortunately,  not  many  message  editors support multiple
  160.     forward (reply) links well, if  at all; however, being early
  161.     days for the Squish  format, which specifically does support
  162.     this, means that it opens the possibility for software, such
  163.     as SQLink (and  MaltEd) to do that in  the future. Certainly
  164.     Maximus  itself will  display multiple  forward links  where
  165.     they  exist, and  fully supports  generation of  MSGID/REPLY
  166.     control information.
  167.  
  168.     You will  find that in  some conferences, using  MSGID/REPLY
  169.     information will not be  useful, especially in special cases
  170.     such  as  gated  newsgroups  or  areas  where  the  software
  171.     predominantly   in   use   does   not   support  MSGID/REPLY
  172.     information. You  can disable SQLink  from looking at  those
  173.     areas, and  optionally allow "SQUISH  LINK" to take  care of
  174.     them instead. (See below)
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.     PROGRAM USAGE
  185.     -------------
  186.  
  187.     First, note that two executables are supplied; SQLink.exe is
  188.     for MSDOS systems, SQLinkP.exe is for OS/2 systems. Both are
  189.     16-bit, and so are compatible with 8088 systems under MSDOS,
  190.     and can be run under OS/2 1.2 and later.  The protected mode
  191.     OS/2 version is HPFS compatible.
  192.  
  193.     The simplest use of SQLink is to  run it in the same area as
  194.     your  SQUISH.CFG  with the "-all" switch.  It  will  process
  195.     all echomail areas  (marked by the "EchoArea"  keyword)  and
  196.     link reply threads.
  197.  
  198.     In reality, you will probably only do this once. Thereafter,
  199.     you  would maintain  the  reply  links when  tossing inbound
  200.     mail. You should also note that existing reply links will be
  201.     automatically maintained even after  a Squish area is tossed
  202.     to or messages  culled by age after using  SQPACK (and Renum
  203.     days).  Messages  in  Squish  areas  are  not threaded by an
  204.     arbitrary  "message number",  and all  messages maintain  an
  205.     internal identifier  which stays with that  message while it
  206.     still  resides in  your message  base. It  is therefore only
  207.     necessary  to re-link  an area  to remove  obsolete links to
  208.     messages  which  no  longer  exist,  and  add  references to
  209.     messages newly added to the area.
  210.  
  211.     The format of the SQLink command line is:
  212.  
  213.  
  214.     SQLINK [-c file] [-a file] [-f file] [-n] [-all] [-k] [areas]
  215.  
  216.     All command line arguments  are optional. If the environment
  217.     variable "SQUISH" is set, the "-c arg" option may be omitted
  218.     and a file  if called  "SQUISH.CFG"  does  not exist  in the
  219.     current directory, the file  to which  this variable  points
  220.     will be used  (this emulates  the same behaviour  as  Squish
  221.     itself).
  222.  
  223.     Switches:
  224.  
  225.       -c <squish.cfg>       Specifies  the   path,  relative  or
  226.                             absolute, of your SQUISH.CFG (it can
  227.                             in fact  be any name,  but it should
  228.                             be  a   valid  squish  configuration
  229.                             file).  Note  that  only "EchoArea",
  230.                             "NetArea", "DupeArea" and  "BadArea"
  231.                             lines are read  from this file,  and
  232.                             all other lines are ignored.  SQLink
  233.                             MUST    find    a    valid    squish
  234.                             configuration file in  order to run,
  235.                             except if the -a switch is used.
  236.  
  237.       -a <areas.bbs>        Specifies  the path  of a  text file
  238.                             which uses the  AREAS.BBS format for
  239.                             message area specification. This may
  240.                             be   used  as   an  alternative   or
  241.                             suppliment  to  reading  a  file  in
  242.                             SQUISH.CFG   format.    Only   areas
  243.                             preceeded by the '$' which indicates
  244.                             that it is in  Squish format will be
  245.                             processed. Note that  it is quite ok
  246.                             if both squish.cfg and areas.bbs are
  247.                             specified and  used. Duplicated tags
  248.                             are automatically eliminated.
  249.  
  250.  
  251.       -f <echotoss.log>     An  optional   path    to   a   file
  252.                             containing  echomail  tags.  Used in
  253.                             combination with  SQUISH.CFG (and/or
  254.                             AREAS.BBS),  this  limits  Sq-link's
  255.                             activity to just those areas. SQUISH
  256.                             (using its  -f  option), Maximus and
  257.                             many editors produce such a file.
  258.  
  259.       -n                    Requests   that   SQLink  link   the
  260.                             the netmail area,  even if its  area
  261.                             name is  not found in  ECHOTOSS.LOG.
  262.                             The command  "SQLINK -n"  links  all
  263.                             Squish format netmail areas.
  264.  
  265.       -k                    This option only  has meaning if the
  266.                             -f  option  is  used  to  specify an
  267.                             echotoss.log  file.  It  is  used to
  268.                             either   automatically   delete  the
  269.                             echotoss.log file  after processing,
  270.                             or,  if not  all areas  described in
  271.                             that  file  have  for  one reason or
  272.                             another  been  processed,  then only
  273.                             the areas actually linked have their
  274.                             tags removed from this file.
  275.  
  276.       -all                  This switch tells Sqlink to link all
  277.                             areas found.  This was  the  default
  278.                             behaviour  with previous versions of
  279.                             SQLink.
  280.  
  281.       [area ...]            One or  more area tags  which are to
  282.                             be linked. This may be combined with
  283.                             the  -f switch  to force  linkage of
  284.                             some areas even  though they are not
  285.                             specified in the echotoss.log.
  286.  
  287.  
  288.  
  289.     As   SQLink  processes   squish  areas,   it  displays  area
  290.     statistics as follows:
  291.  
  292.     SQLink; Squish MSGID/REPLY Linker [MSDOS]; Version 1.20
  293.     Copyright 1992-93 by David Nugent & Unique Computing Pty Ltd.
  294.  
  295.     Linking MUFFIN                 Read 0023/0425 Link 0121/0398
  296.          ^                              ^    ^         ^    ^
  297.          |                              |    |         |    |
  298.          +-- Area tag                   A    B         C    D
  299.  
  300.  
  301.     A>  Reset links         These are messages  where reply link
  302.                             information  has   become  obsolete;
  303.                             where  links have  been specifically
  304.                             cleared because they no longer exist
  305.                             (you should  have a large  number of
  306.                             these when you first run Sq-link).
  307.  
  308.     B>  Total read          This  will  agree   with  the  total
  309.                             number of messages  currently in the
  310.                             area.
  311.  
  312.     C>  New links           Messages  where new  links have been
  313.                             added.  Again,  the   first  run  of
  314.                             SQLink on  an area will  see a large
  315.                             number of these.
  316.  
  317.  
  318.     D>  Linked messages     This  number  represents  the  total
  319.                             number   of    messages   containing
  320.                             message  link  information  (some of
  321.                             which may not  be linked anyway). In
  322.                             deciding  whether to  use true reply
  323.                             linking  or  not  for  an  area, you
  324.                             should  look at  this statistic  and
  325.                             compare  it  against  B  to  see how
  326.                             predominate reply  link formation is
  327.                             in that conference.
  328.  
  329.  
  330.  
  331.     SUPPRESS LINKING
  332.     ----------------
  333.  
  334.     As has already been mentioned, it is sometimes not worth the
  335.     time and trouble to reply  link particular areas using reply
  336.     link information. You can  prevent SQLink from linking those
  337.     areas by using a "-nl" (no link) switch on the corresponding
  338.     EchoArea  line in  your SQUISH.CFG.  (There is  currently no
  339.     way  to  suppress  linking  areas  which  are  specified  in
  340.     AREAS.BBS format).
  341.  
  342.     Note that this is NOT  a switch that SQUISH will understand,
  343.     but it is nevertheless ignored by SQUISH and will not affect
  344.     the way it works in any way.
  345.  
  346.     Squish will not link a BadArea or DupeArea,  although if one
  347.     of these is found in a given ECHOTOSS.LOG,  the tag will  be
  348.     removed if it needs to be rewritten.
  349.  
  350.  
  351.  
  352.     EXAMPLES
  353.     --------
  354.  
  355.     Most  mail processing  will see  conference areas  re-linked
  356.     after  receipt of  mail. The  following batch  file fragment
  357.     shows an  example of how you  might blend in SQLink  to your
  358.     existing setup:
  359.  
  360.  
  361.     "One pass" mode:
  362.  
  363.     SQUISH -cSQ.CFG -fTOSS.LOG IN OUT SQUASH
  364.     SQLINK -cSQ.CFG -fTOSS.LOG -k
  365.     if exist TOSS.LOG SQUISH -fTOSS.LOG LINK
  366.     if exist TOSS.LOG del TOSS.LOG
  367.  
  368.     This will do  a one pass toss, scan and  pack, followed by a
  369.     link of all  areas which SQLINK is able to  link, and if any
  370.     areas  remain to  be linked,  they will  be "subject linked"
  371.     using that facility in SQUISH.
  372.  
  373.     You  should  be  able  to  adapt  this  to  almost any setup
  374.     involving squish.
  375.  
  376.  
  377.  
  378.     NOTES
  379.     -----
  380.  
  381.     The -Widgets switch can be slow.
  382.  
  383.  
  384.  
  385.     CREDITS
  386.     -------
  387.  
  388.     Squish and Maximus-CBCS are copyright Scott Dudley.
  389.  
  390.     Thanks (again) to Scott, the inventor of the very robust and
  391.     flexible  Squish message  format, which  makes this  program
  392.     possible without  the need to invent  kludges or work around
  393.     shortfalls in the design of the message base format itself.
  394.  
  395.  
  396.  
  397.     AUTHOR
  398.     ------
  399.  
  400.     Can be contacted:
  401.  
  402.         FidoNet             3:632/348@fidonet
  403.         IntlNet             58:4100/1@intlnet
  404.         Admin               33:300/6@admin
  405.         InterNet/ACSNet     davidn@csource.oz.au
  406.         BBS                 +61-3-792-3507, +61-3-794-7949
  407.  
  408.     Surface mail:
  409.  
  410.         David Nugent
  411.         Unique Computing Pty Limited
  412.         PO Box 352
  413.         Doveton, Vic,  3177.
  414.         Australia
  415.  
  416.  
  417.