home *** CD-ROM | disk | FTP | other *** search
/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / OS2 / DATACOM / YRN2-052 / YARN.DOC < prev    next >
Text File  |  1993-12-12  |  20KB  |  595 lines
  1.  
  2.  
  3. YARN(1)                                                                 YARN(1)
  4.  
  5.  
  6.  
  7.      Yarn - offline news storage and reading system
  8.  
  9.      Copyright (c) 1993 Chin Huang
  10.  
  11.      Permission to copy and  distribute  this  material  for  any  purpose  and
  12.      without  fee  is  hereby granted, provided that the above copyright notice
  13.      and this permission notice appear in all  copies.   CHIN  HUANG  MAKES  NO
  14.      REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
  15.      PURPOSE.   IT  IS  PROVIDED  "AS  IS",  WITHOUT  ANY  EXPRESS  OR  IMPLIED
  16.      WARRANTIES.
  17.  
  18.                                  INTRODUCTION
  19.  
  20.      Yarn is a suite of programs for your personal computer, used to store  and
  21.      read USENET news downloaded from a USENET host.
  22.  
  23. FEATURES
  24.  
  25.      -  An import program inserts USENET  articles  into  a  "news  base"  from
  26.         Simple Offline USENET Packet (SOUP) format.
  27.  
  28.      -  For each newsgroup, you specify the number of days  to  keep  articles,
  29.         after  which,  an  expire  program  deletes  them.   However,  articles
  30.         containing an Expires: header are deleted on the date specified in  the
  31.         header.
  32.  
  33.      -  The news base stores only one copy of a cross-posted article.  The news
  34.         base implementation stores multiple articles per file.
  35.  
  36.      -  The Yarn news reader presents articles in threads arranged by  Message-
  37.         ID and References.  The reader program generates SOUP reply packets.
  38.  
  39.      -  Multiple users are supported by storing  separate  configuration  files
  40.         for each user.
  41.  
  42. SYSTEM REQUIREMENTS
  43.  
  44.      -  MS-DOS 3.0 or higher
  45.  
  46.      -  a lot of hard disk storage, depending on how  much  news  you  want  to
  47.         keep.   For  example, the author subscribes to 120 newsgroups including
  48.         some binaries and sources groups, keeping most  articles  for  7  days.
  49.         The amount of disk space used is 40 megabytes.
  50.  
  51.                                  INSTALLATION
  52.  
  53. SET UP DIRECTORIES AND FILES
  54.  
  55.      -  Create a directory named \YARN and  unpack  the  files  from  the  Yarn
  56.         package  into  this  directory.  Choose a disk drive with a lot of free
  57.         space because the  news  base  will  be  stored  here.   Set  the  YARN
  58.         environment variable to the \YARN directory.  For example:
  59.  
  60.  
  61.  
  62.  
  63.  
  64.                                  Version 0.52                                 1
  65.  
  66.  
  67.  
  68.  
  69. YARN(1)                                                                 YARN(1)
  70.  
  71.  
  72.              MKDIR C:\YARN
  73.              SET YARN=C:\YARN
  74.  
  75.  
  76.      -  Create a directory in which Yarn will store your user information.  Set
  77.         the  HOME  environment variable to this directory.  This will be called
  78.         the <home> directory.  For example:
  79.  
  80.              MKDIR C:\JIM
  81.              SET HOME=C:\JIM
  82.  
  83.  
  84.      -  Create the directory <home>\YARN and copy the file \YARN\CONFIG to this
  85.         directory.  For example:
  86.  
  87.              MKDIR C:\JIM\YARN
  88.              COPY \YARN\CONFIG C:\JIM\YARN\CONFIG
  89.  
  90.  
  91.      -  Set the environment variable TZ to your time zone.  The format  of  the
  92.         TZ string is
  93.  
  94.              zzz[+/-]h[h][ddd]
  95.  
  96.  
  97.         zzz is a three character field representing the name of the time zone.
  98.  
  99.         [+/-]h[h] is an optionally signed number representing  the  local  time
  100.         zone's difference from Greenwich Mean Time (GMT) in hours.
  101.  
  102.         ddd is an optional three character field that represents  the  name  of
  103.         the local time zone's daylight saving time.
  104.  
  105.         If no TZ environment variable is set, a default TZ=EST5EDT is assumed.
  106.  
  107.      Put the above SET  commands  in  your  AUTOEXEC.BAT  file  to  ensure  the
  108.      environment  settings  persist after the next time you reboot your system.
  109.      (If you are installing Yarn  for  OS/2,  put  the  SET  commands  in  your
  110.      CONFIG.SYS file instead.)
  111.  
  112. EDIT THE CONFIGURATION FILE
  113.  
  114.      Edit the configuration file <home>\YARN\CONFIG  to  suit  the  user.   The
  115.      following entries in the configuration file must be set.
  116.  
  117.      user      Set this to your login name on the host from which you  download
  118.                and upload USENET news.
  119.  
  120.      host      Set this to the full domain name of your host.
  121.  
  122.      name      Set this to your full name.  This is the name  that  appears  in
  123.                parentheses on the From: header in messages you send.
  124.  
  125.      editor    Set the name  of  the  editor  program  to  run  when  you  send
  126.                messages.  The program must be in your PATH.
  127.  
  128.  
  129.  
  130.                                  Version 0.52                                 2
  131.  
  132.  
  133.  
  134.  
  135. YARN(1)                                                                 YARN(1)
  136.  
  137.  
  138.      reply     Specify the full path of the SOUP reply packet file  where  your
  139.                outgoing messages are stored.  If the reply packet file does not
  140.                exist, it is created when you post an article  or  send  a  mail
  141.                message  from  the  reader  program.   When  you exit the reader
  142.                program, the reply packet is ready to upload to your host.
  143.  
  144. SET UP MAIL ALIASES
  145.  
  146.      A mail alias is a word representing one or more mail addresses.  If a mail
  147.      alias  appears  in  a  To:,  Cc:,  or Bcc: header, it is replaced with the
  148.      corresponding address list when the message is sent.
  149.  
  150.      A mail alias is defined in the configuration file with the statement
  151.  
  152.           alias <name>=<addresses>
  153.  
  154.      where <name> is the name of the alias and <addresses> is a list of one  or
  155.      more addresses.
  156.  
  157. SET UP OTHER USERS
  158.  
  159.      To define another user, create a home directory for the user  and  set  up
  160.      the <home>\YARN\CONFIG file as described above.  To run Yarn as that user,
  161.      set the HOME environment variable to the user's home directory.
  162.  
  163. ENVIRONMENT
  164.  
  165.      These enviroment variables modify the behaviour of Yarn if they are set.
  166.  
  167.      EDITOR    Specifies the external editor  program,  overriding  the  editor
  168.                specified in the configuration file.
  169.  
  170.      YARNRC    This is the path of an  alternate  configuration  file  to  read
  171.                instead of the default one.
  172.  
  173. CREATE LIST OF ACTIVE NEWSGROUPS
  174.  
  175.      You must inform Yarn of every newsgroup you will be importing  by  running
  176.      the command
  177.  
  178.           newgroup <name> <keepDays>
  179.  
  180.      where <name> is the newsgroup name and <keepDays> is the  number  of  days
  181.      that  articles  in  the  newsgroup  will be kept before the expire program
  182.      deletes them.  If you later want to change the number of  keep  days,  run
  183.      this command again, specifying the new keep days value.
  184.  
  185.      Instead of naming a newsgroup on the command line, you can specify a  text
  186.      file  containing a list of newsgroup names.  Every newsgroup listed in the
  187.      file is assigned the keep days value.
  188.  
  189.           newgroup @<file> <keepDays>
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                                  Version 0.52                                 3
  197.  
  198.  
  199.  
  200.  
  201. YARN(1)                                                                 YARN(1)
  202.  
  203.  
  204. REMOVE NEWSGROUP FROM ACTIVE LIST
  205.  
  206.      To remove a newsgroup from the active newsgroup list, run the command
  207.  
  208.           rmgroup <name>
  209.  
  210.      where <name> is the newsgroup name.
  211.  
  212.                                    OPERATION
  213.  
  214. IMPORT NEWS AND MAIL
  215.  
  216.      To import messages from SOUP format, run
  217.  
  218.           import <file>
  219.  
  220.      where <file> is the path of the SOUP file.  The import program takes these
  221.      options.
  222.  
  223.      -n        Do not delete the packet file.
  224.  
  225.      -q        Operate in quiet mode.  Do not list imported article numbers.
  226.  
  227.      If the import program finds a newsgroup in the packet that is not  in  the
  228.      active newsgroup list, it adds the newsgroup to the active list.  The keep
  229.      days for the added newsgroup is specified by the  "keep"  setting  in  the
  230.      configuration  file.   For example, if the configuration file contains the
  231.      line
  232.  
  233.           keep=7
  234.  
  235.      then articles are kept in the newsgroup for 7 days.
  236.  
  237. EXPIRE NEWS
  238.  
  239.      Periodically run the expire program to delete old articles from  the  news
  240.      base.  The program accepts these options:
  241.  
  242.      -d<n>     Assume it is <n> days in the future.  Use this option to  expire
  243.                articles before they normally would have been expired.
  244.  
  245.      -n        Do not actually delete any articles.  Used for testing.
  246.  
  247. READ NEWS
  248.  
  249.      Run the yarn program to read news and mail.  The reader  program  operates
  250.      in  several  modes -- the newsgroup selection level, the article selection
  251.      level, and the article reading level.
  252.  
  253.      In the newsgroup selection level,  yarn  displays  a  window  listing  the
  254.      newsgroups  you are subscribed to along with the number of unread articles
  255.      in each newsgroup.  You can subscribe, unsubscribe or rearrange the  order
  256.      of  newsgroups  in  this  list.   Press  the  [Ins]  key to subscribe to a
  257.      newsgroup.  This brings up a list of unsubscribed newsgroups.  To  make  a
  258.      selection,  use the arrow keys to move the highlight to the newsgroup, and
  259.      then press the [Enter] key.  The selected newsgroup is inserted  into  the
  260.  
  261.  
  262.                                  Version 0.52                                 4
  263.  
  264.  
  265.  
  266.  
  267. YARN(1)                                                                 YARN(1)
  268.  
  269.  
  270.      subscribed newsgroup list.  Press the [Del] key to  unsubscribe  from  the
  271.      highlighted  newsgroup.   To move a newsgroup in the list, press the [Del]
  272.      key to remove it, position the highlight to  the  desired  location,  then
  273.      press the [Ins] key and reinsert the newsgroup.
  274.  
  275.      By selecting a newsgroup, you go to the  article  selection  level,  where
  276.      yarn  presents  a list of the subjects of each article.  You can select an
  277.      article to read from this list, taking you to the article reading level.
  278.  
  279. NEWSGROUP SELECTION LEVEL
  280.  
  281.      These commands are available in the newsgroup selection level.
  282.  
  283.      Down Arrow
  284.           Move to the next newsgroup.
  285.  
  286.      Up Arrow
  287.           Move to the previous newsgroup.
  288.  
  289.      Tab, Alt-N
  290.           Move to the next newsgroup that contains unread articles.
  291.  
  292.      Shift-Tab, Alt-P
  293.           Move to the previous newsgroup that contains unread articles.
  294.  
  295.      Space
  296.           Go to the article selection level, listing only unread articles.
  297.  
  298.      Enter
  299.           Go to the article selection level, listing all articles.
  300.  
  301.      Ins, Alt-S
  302.           Subscribe to a newsgroup and insert  the  newsgroup  at  the  current
  303.           position.
  304.  
  305.      Del, Alt-U
  306.           Unsubscribe from the highlighted newsgroup.
  307.  
  308.      Alt-A
  309.           Post an article to the highlighted newsgroup.
  310.  
  311.      Esc  Exit program
  312.  
  313. ARTICLE SELECTION LEVEL
  314.  
  315.      These commands are available in the article selection level.
  316.  
  317.      Down Arrow
  318.           Move to the next article.
  319.  
  320.      Up Arrow
  321.           Move to the previous article.
  322.  
  323.      Tab  Move to the first article of the next thread.
  324.  
  325.  
  326.  
  327.  
  328.                                  Version 0.52                                 5
  329.  
  330.  
  331.  
  332.  
  333. YARN(1)                                                                 YARN(1)
  334.  
  335.  
  336.      Shift-Tab
  337.           Move backwards to the previous article beginning a thread.
  338.  
  339.      Space, Enter
  340.           Read the article.
  341.  
  342.      Del, Alt-N
  343.           Mark the article as read and go to the next unread article.
  344.  
  345.      Ins  Mark the article as unread.
  346.  
  347.      Alt-O
  348.           Save the current article through to the last article in the thread to
  349.           a folder.
  350.  
  351.      Alt-S
  352.           Save the current article through to the last article in the thread to
  353.           a file.  If the file already exists, the articles are appended to the
  354.           file.  The program prompts for a file name.  If you don't give a full
  355.           path name, the file is stored in the directory <home>/News.
  356.  
  357.      Alt-W
  358.           Same at Alt-S, except omit the article headers.
  359.  
  360.      Alt-K
  361.           Mark the current article through to the last article in the thread as
  362.           read.
  363.  
  364.      Alt-C
  365.           Mark all articles in the newsgroup as read.
  366.  
  367.      Alt-A
  368.           Post an article to the newsgroup.
  369.  
  370.      Esc  Return to the newsgroup selection level.
  371.  
  372. ARTICLE READING LEVEL
  373.  
  374.      These commands are available in the article reading level.
  375.  
  376.      Down Arrow
  377.           Scroll one line down.
  378.  
  379.      Up Arrow
  380.           Scroll one line up.
  381.  
  382.      PgDn, Space
  383.           Show next page.
  384.  
  385.      PgUp Show previous page.
  386.  
  387.      n    Mark the article as read and show the next unread article.
  388.  
  389.      N    Show next article.
  390.  
  391.  
  392.  
  393.  
  394.                                  Version 0.52                                 6
  395.  
  396.  
  397.  
  398.  
  399. YARN(1)                                                                 YARN(1)
  400.  
  401.  
  402.      p    Show previous unread article.
  403.  
  404.      P    Show previous article.
  405.  
  406.      a, Alt-A
  407.           Post an article to the newsgroup.
  408.  
  409.      f    Post a followup article.
  410.  
  411.      F    Post a followup article, quoting the original article.
  412.  
  413.      r    Mail a reply to the author of the article.
  414.  
  415.      R    Mail a reply, quoting the original article.
  416.  
  417.      o    Save the article to a folder.
  418.  
  419.      s    Save the article to a file.  If the file already exists, the  article
  420.           is  appended  to  the file.  The program prompts for a file name.  If
  421.           you don't give a full path name, the file is stored in the  directory
  422.           <home>/News.
  423.  
  424.      w    Same as s except omit article headers.
  425.  
  426.      x    ROT13 decrypt the article.
  427.  
  428.      j, Del
  429.           Mark the article as read.
  430.  
  431.      m, Ins
  432.           Mark the article as unread.
  433.  
  434.      k, Alt-K
  435.           Mark this article and the rest of the articles in the thread as read.
  436.  
  437.      Alt-C
  438.           Mark all the articles in the newsgroup as read.
  439.  
  440.      v    Toggle verbose headers.
  441.  
  442.      C    Cancel the article.  You must be the author to be able to cancel  the
  443.           article.
  444.  
  445.      z    Supersede the article.   You  must  be  the  author  to  be  able  to
  446.           supersede the article.
  447.  
  448.      =    Return to the article selection level.
  449.  
  450.      Esc  Return to the newsgroup selection level.
  451.  
  452. READ MAIL
  453.  
  454.      To read mail, press [Alt-M] at the newsgroup selection level.  This brings
  455.      up  a  list  of  mail messages you received.  If you have no mail, you are
  456.      given the opportunity to send mail.
  457.  
  458.  
  459.  
  460.                                  Version 0.52                                 7
  461.  
  462.  
  463.  
  464.  
  465. YARN(1)                                                                 YARN(1)
  466.  
  467.  
  468.      Press [Alt-F] at the newsgroup selection level  to  bring  up  a  list  of
  469.      folders.  You can select a folder to read from this list.
  470.  
  471.      If you start yarn with the -m option, you  go  directly  to  reading  your
  472.      received  mail  and  skip  reading  news.   If  you start yarn with the -f
  473.      option, you go directly to the folder list and skip reading news.
  474.  
  475. EDIT REPLIES
  476.  
  477.      The Yarn reader allows you to edit the messages in the reply  packet.   At
  478.      the  newsgroup selection level, press [Alt-R] to display a list of folders
  479.      in the reply packet.  The reply packet may  contain  up  to  two  folders,
  480.      ``mail''  which  holds  outgoing  mail  messages, and ``news'' which holds
  481.      outgoing USENET articles.
  482.  
  483.      By selecting a folder, you go to the message selection  level,  where  the
  484.      program  lists  the messages in the folder.  Press the [Del] key to delete
  485.      the currently highlighted message.  Press [Alt-E] to edit the message.
  486.  
  487.      To view a message, select it from the message selection  level.   While  a
  488.      message is displayed, pressing the 'd' key deletes the message.  Press the
  489.      'e' key to edit the message.
  490.  
  491. QUESTIONS AND ANSWERS
  492.  
  493.      ``How do I create SOUP files on my UNIX host?''
  494.  
  495.           The uqwk program creates and processes SOUP files on your UNIX  host.
  496.           It  is  available  by anonymous FTP from ftp.gte.com in the /pub/uqwk
  497.           directory.
  498.  
  499.           To create a SOUP download packet, named "down.zip" in  this  example,
  500.           run these commands on your UNIX host:
  501.  
  502.                uqwk +n +L
  503.                zip down.zip AREAS *.MSG
  504.  
  505.           Download the down.zip file to your PC.  Run this command on  your  PC
  506.           to insert the messages into the Yarn news base:
  507.  
  508.                import down.zip
  509.  
  510.           When you send mail or post articles, the Yarn reader creates  a  SOUP
  511.           reply packet, named "up.zip" in this example.  Upload the up.zip file
  512.           to your UNIX host.  Run these commands on your UNIX host to send  the
  513.           messages in the reply packet:
  514.  
  515.                unzip -U up.zip
  516.                uqwk -m -n +L -RREPLIES
  517.  
  518.  
  519.      ``Sometimes when I select a newsgroup by pressing the space bar  from  the
  520.      newsgroup  selection  level,  yarn  lists less articles than the number of
  521.      unread articles shown.''
  522.  
  523.  
  524.  
  525.  
  526.                                  Version 0.52                                 8
  527.  
  528.  
  529.  
  530.  
  531. YARN(1)                                                                 YARN(1)
  532.  
  533.  
  534.           This occurs if  the  newsgroup  you  selected  contains  cross-posted
  535.           articles  that  you  already  read in another newsgroup.  The program
  536.           marks these articles as read and updates the count of unread articles
  537.           when you select the newsgroup.
  538.  
  539.      ``After running expire, I reduced the keep days for a  newsgroup  and  ran
  540.      expire again, but it didn't delete any more articles.''
  541.  
  542.           Each article is assigned an expiry date after which  it  is  deleted.
  543.           The  expire program deletes articles having an expiry date older than
  544.           the current date.   The  article  storage  scheme  requires  that  an
  545.           article's  expiry  date  be set when the article is imported into the
  546.           news base.  Once  imported,  the  article's  expiry  date  cannot  be
  547.           changed.   When  you  change  the keep days for a newsgroup, you only
  548.           change how long you keep articles  that  are  subsequently  imported.
  549.           You  don't  affect  the  expiry dates of articles already in the news
  550.           base.
  551.  
  552.      ``What is the junk newsgroup?''
  553.  
  554.           When the import program encounters an article that doesn't belong  to
  555.           any of the groups in the active newsgroup list, it tosses the article
  556.           into the junk newsgroup.  This usually shouldn't happen with properly
  557.           configured software.
  558.  
  559. FILES
  560.  
  561.      <home>/mail             Folder directory
  562.      <home>/news             Default save directory
  563.      <home>/replies          Reply work directory
  564.      <home>/yarn             User configuration directory
  565.      <home>/yarn/config      User configuration file
  566.      <home>/yarn/newsrc      Newsgroup subscription file
  567.      <home>/yarn/readart.*   Read cross-posted article lookup table
  568.  
  569.      <yarn>/active           Active newsgroup file
  570.      <yarn>/history.*        Article history lookup table
  571.      <yarn>/index            Article index directory
  572.      <yarn>/news             Article file directory
  573.  
  574.                                ACKNOWLEDGEMENTS
  575.  
  576.      This product uses the SPAWNO routines by Ralf Brown to minimize memory use
  577.      while shelling to DOS and running other programs.
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.                                  Version 0.52                                 9
  593.  
  594.  
  595.