home *** CD-ROM | disk | FTP | other *** search
/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / TFILE080.RAR / TOPFILE.DOC < prev    next >
Encoding:
Text File  |  1996-03-22  |  21.0 KB  |  450 lines
  1.  
  2.         ╒═════════════════════════════════════════════════════════════╕
  3.         │  ┌───────┐┌──────┐┌──────┐     ┌──────┐┌─┐┌─┐     ┌──────┐  │
  4.         │  └───────┘└──────┘└──────┘     └──────┘└─┘└─┘     └──────┘  │
  5.         │     ┌─┐   ┌─┐  ┌─┐┌──────┐     ┌────┐  ┌─┐┌─┐     ┌──────┐  │
  6.         │     │ │   │ │  │ ││ ┌────┘     │ ┌──┘  │ ││ │     │ ┌────┘  │
  7.         │     │ │   │ └──┘ ││ │          │ │     │ ││ └────┐│ └────┐  │
  8.         │     └─┘   └──────┘└─┘          └─┘     └─┘└──────┘└──────┘  │
  9.         ╘═════════════════════════════════════════════════════ v0.80 ═╛
  10.  
  11.                    A Top Downloaded Files Statistic Producer
  12.                      (c)Copyright 1994-1996, Dwayne Heaton
  13.  
  14.              ╒═══════════════════════════════════════════════════╕
  15.              │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ Index ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  16.              ╞═══════════════════════════════════════════════════╡
  17.              │ Introduction                                      │
  18.              │   What is TOPFILE?                            1.1 │
  19.              │   System Hardware & software requirements     1.2 │
  20.              │   Disclaimer and Licensing agreement          1.3 │
  21.              │ Installation                                  2.0 │
  22.              │ Usage                                             │
  23.              │   Command Line                                3.1 │
  24.              │   The TOPFILE.CTL file                        3.2 │
  25.              │   The TOPFILE.EXC file                        3.3 │
  26.              │ Bug Reports and Contacting the Author         4.0 │
  27.              │ Credits and Thanks                            5.0 │
  28.              └───────────────────────────────────────────────────┘
  29.  
  30.  
  31.  
  32. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  33. │  1.1 │  What is TOPFILE ? ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  34. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  35.  
  36.   TOPFILE is a 'Top Downloaded Files' ASCII/ANSi/AVATAR bulletin generator.
  37.  
  38.   It was originally written to produce a screen for my users to view, showing
  39.   the most popular files on my system. I know that there are several programs
  40.   out there that also perform the same function, but I wanted to try out my
  41.   programming skills and write my own. Thus, TOPFILE was born....
  42.  
  43.   I designed it to produce the ASCII/ANSi/ATATAR bulletins as quickly as
  44.   possible with the obsolute minumin of configuration. I hope I've suceeded.
  45.  
  46.   And finally, the program is NOT crippled in any way whatsoever, and DOESN'T
  47.   require any registration fees at all :-)
  48.  
  49.  
  50. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  51. │  1.2 │ System hardware and software requirements ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  52. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  53.  
  54.   *  An IBM PC, XT, AT or 100% compatible PC with a hard disk.
  55.   *  Microsoft MS-DOS, IBM PC-DOS or DR-DOS version 3.30 or later. Version
  56.      5.0 or later is recommended.
  57.   *  At least 128KB of RAM available.
  58.  
  59.   *  At the moment TOPFILE only supports the following BBS filebases:
  60.        - RemoteAccess    Copyright (c) Wantree Development & Andrew Milner
  61.  
  62.   *  TOPFILE has been successfully tested with the file base as used in
  63.      Remote Access v2.00, v2.01, v2.02 and v2.50.
  64.  
  65.   *  TOPFILE has been successfully tested with MS-DOS 5.0, 6.0, 6.2 and
  66.      6.22, 4DOS 5.0 and 5.5, IBM OS/2 WARP, Novell Netware Lite v1.1,
  67.      Novell Netware v3.12 on systems equiped with Intel/AMD 8086, 80286,
  68.      80386, 80486 and Pentium processors.
  69.  
  70.   *  OS/2 is a registered trademark of IBM Corporation
  71.      MS-DOS is a registered trademark of Microsoft Corporation
  72.  
  73.      All other programs are copyright and/or trademarked by their
  74.      respective author unless otherwise noted.
  75.  
  76.  
  77. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  78. │  1.3 │ Disclaimer and Licensing Agreement ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  79. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  80.  
  81.     TOPFILE consists of all files contained within the distribution archive.
  82.     Before running TOPFILE, you must read and agree to the following
  83.     conditions. If you do not or can not agree to and accept the following
  84.     conditions, you are prohibited from using TOPFILE.
  85.  
  86.  ■  The documentation and accompanying program are copyrighted material 
  87.     designed, produced and tested by the author of the software.
  88.  
  89.  ■  TOPFILE is distributed as FREEWARE *NOT* Public Domain!
  90.  
  91.  ■  Since this product is FREEWARE, you are actively encouraged to copy and
  92.     distribute it as long as it remains in its complete form with all support
  93.     and documentation files. No files may be added or taken away from the
  94.     original archived form in which TOPFILE is distributed.
  95.  
  96.  ■  Shareware vendors and BBSes may redistribute this product as long as they
  97.     do not charge any money or monies for the product. Cost of distribution
  98.     media (be it disk, CD-ROM, tape, etc) and/or subscription charges are
  99.     acceptable.
  100.  
  101.  ■  I (Dwayne Heaton) am NOT oligated to provide new versions or support for
  102.     TOPFILE.
  103.  
  104.  ■  In the event that future versions of TOPFILE are released, Dwayne Heaton
  105.     reserves the right not to release them under the FREEWARE concept and to
  106.     charge a nominal fee should it be deemed appropriate.
  107.  
  108.  ■  Although every care and attention has been taken to write and test the
  109.     program to make sure that it does what this documentation states, the
  110.     program is provided as it is, without warranty or guarantee of any kind,
  111.     either expressed or implied, as to the quality or performance of this
  112.     program, except that it will occupy disk space.
  113.  
  114.  ■  The author shall not be held liable to you or anyone else for any direct,
  115.     indirect, incidental or consequential damages, including any lost profits,
  116.     lost savings, lost business, which may result from the use or inability 
  117.     to use this program.
  118.  
  119.  ■  You are NOT allowed to do any disassembling, reverse engineering, creating
  120.     patches for TOPFILE and things alike.
  121.  
  122.  ■  Your use of this program constitutes your agreement to this disclaimer and
  123.     your release of the author from any form of liability or litigation.
  124.  
  125.  ■  The source code or part of it, is NOT available.
  126.  
  127.  ■  All rights reserved worldwide.
  128.  
  129.  
  130. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  131. │  2.0 │ Installation ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  132. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  133.  
  134.   I tried to make using TOPFILE as easy to use as I possibly could. Just
  135.   unpack the archive into one directory, and its ready to use straight away.
  136.  
  137.   A new feature of TOPFILE (as from v0.74) is the ability to configure the
  138.   program to suit your system.
  139.  
  140.   The config file ('TOPFILE.CTL') must be in the same directory that you are
  141.   running TOPFILE from. It doesn't have to exist, but it should exist if you
  142.   want greater control over the program (since it gives you more options than
  143.   the command line). The control (config) file is explained in more detail
  144.   in section 3.2, 'The TOPFILE.CTL file'
  145.  
  146.   TOPFILE will now allow you to specify a list of file names and or file
  147.   areas you wish excluded from the bulletin(s). This file is explained in
  148.   more detail in section 3.3, 'The TOPFILE.EXC file'
  149.  
  150.   You will need to have the RA environment variable set, so that it points
  151.   to your Remote Access system directory, but if you are running RA without
  152.   any problems, this should be already be set  :)
  153.  
  154.   Once you have installed TOPFILE all you need to do is run it to produce
  155.   the ASCII/ANSi/AVATAR bulletin. The bulletins created are placed in the
  156.   main Text Files directory as specified in your RemoteAccess configuration.
  157.  
  158.   You could run TOPFILE after every call to the BBS, or you could run it in
  159.   any daily maintenance events.
  160.  
  161.  
  162.   Note - If you have a large number of file areas and/or files TOPFILE can
  163.          take some time. (Performance is improved if you use a disk caching
  164.          program)
  165.  
  166.          TOPFILE will try and use SHARE to open all files it needs. This
  167.          will allow multi-line BBS's to run it without getting any file
  168.          sharing violations.
  169.  
  170.  
  171. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  172. │  3.1 │ Command Line ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  173. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  174.  
  175.   There are a few command-line options you can use for greater control over
  176.   the program's operation. When used in conjunction with the control file
  177.   these options over-ride any settings in the file.
  178.  
  179.   If you do not specify any options TOPFILE will use its internal defaults
  180.   of ignoring FREE and MISSING files, including every file, not performing
  181.   a secondary sort (see -SORTAREA & -SORTNAME below), generating ASCII and
  182.   ANSi screens and auto detecting the display type..
  183.  
  184.  
  185.   TOPFILE -?              Shows a brief help screen with all options listed
  186.                           on it.
  187.  
  188.           -HELP           Same as above.
  189.  
  190.           -NOFREE         This will tell TOPFILE to exclude any file that
  191.                           is a free download to users in the bulletin.
  192.                           (A free file is one that has been flagged as a
  193.                            free download or any file that is in an Area
  194.                            which has been set to free.)
  195.  
  196.           -USEAREA        This forces TOPFILE to use the area number and
  197.                           area description instead of using the file
  198.                           description. Useful if you have alot of files
  199.                           with borders..
  200.  
  201.           -NOMISSING      This will make TOPFILE to exclude any file that
  202.                           has been flagged as missing.
  203.  
  204.           -NOASCII        Stops TOPFILE producing ASCII bulletins
  205.  
  206.           -NOANSI         Stops TOPFILE producing ANSi bulletins
  207.  
  208.           -NOAVATAR       Stops TOPFILE producing AVATAR bulletins
  209.  
  210.           -SORTNAME       Performs a secondary sort on all files with the
  211.                           same download count, and orders them by filename
  212.  
  213.           -SORTAREA       Performs a secondary sort on all files with the
  214.                           same download count, and orders them by file area
  215.                           number.
  216.  
  217.           -SEC=<num>      The maximium list security to include in the
  218.                           bulletin.
  219.  
  220.  
  221. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  222. │  3.2 │ The TOPFILE.CTL File ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  223. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  224.  
  225.   As said before the control (config) file will allow you to fully configure
  226.   TOPFILE to your system. It will allow you to set all the options that the
  227.   command line does, but with has several more options.
  228.  
  229.   If this is a new installation just run SETUP.EXE to create an initial
  230.   TOPFILE.CTL file with default settings.
  231.  
  232.   If this is an upgrade installation, run SETUP.EXE to update your existing
  233.   TOPFILE.CTL with any new options. Follow the on screen information.
  234.  
  235.   The options can be in any order, but the option and the value must be
  236.   separated by at least one space. Any line starting with a ';' is counted
  237.   as a comment line and isn't processed.
  238.  
  239.   Here is a list of options you can use, and a description or what they do.
  240.                       
  241.    BBSSoftware           BBS Software you are using.
  242.    Description           Description type to use.
  243.    IncludeFree           Whether to include free files in the bulletin.
  244.    IncludeMissing        Whether to include missing files in the bulletin.
  245.    ASCII                 Produce ASCII bulletins.
  246.    ANSi                  Produce ANSi bulletins.
  247.    AVATAR                Produce AVATAR bulletins.
  248.    EnterPrompt           Add the RemoteAccess 'Wait for Enter' control
  249.                          character.
  250.    FileSort              The Top Files secondary sort type.
  251.    AreaSort              The Area Statistics primary sort type.
  252.    HighSecurity          Highest FileArea ListSecurity to include.
  253.  
  254.    Main.Title            The 'Top xx Files on ..' colour.
  255.    Main.Border           The colour of the box around all the list of files.
  256.  
  257.    TopFiles.Filename     Which colour the filename is displayed in.
  258.    TopFiles.DlCount      Colour of the times downloaded count.
  259.    TopFiles.FileSize     The colour of the size (in Kb) of the file.
  260.    TopFiles.Description  The colour you want the file description to be.
  261.  
  262.    AreaStat.AreaNum      What colour the Area number is displayed in.
  263.    AreaStat.Description  The colour of the area description.
  264.    AreaStat.FileCount    The colour of the area file count field.
  265.    AreaStat.SizeCount    The colour of the area total size field.
  266.    AreaStat.Downloads    The colour of the area downloads count.
  267.  
  268.    ASC_TopFiles          The filename of the Top Files ASCII bulletin.
  269.    ANS_TopFiles          The filename of the Top Files ANSi bulletin.
  270.    AVT_TopFiles          The filename of the Top Files AVATAR bulletin.
  271.    ASC_AreaStat          The filename of the Area Statistics ASCII bulletin.
  272.    ANS_AreaStat          The filename of the Area Statistics ANSi bulletin.
  273.    AVT_AreaStat          The filename of the Area Statistics AVATAR bulletin.
  274.  
  275.  
  276.   BBSSoftware accepts the following values : RA20x, RA250
  277.  
  278.   Description accepts the following values : File, Area
  279.  
  280.   IncludeFree, IncludeMissing, Ascii, Ansi, Colour, Sort accept the following
  281.   values : Yes, No, On, Off, True, False
  282.  
  283.   FileSort accepts the following values : File, Area, None
  284.  
  285.   AreaSort accepts the following calues : None, File, Size, Downloads.
  286.  
  287.   IncludeSysop, UseHandles, UseHidden, ASCII, ANSi and AVATAR accept the
  288.   following values : Yes or No, On or Off, True or False
  289.  
  290.   A??_TopFiles and A??_AreaStat reconize the following values : No, Off,
  291.   False.  Any thing other these will be interpreted as a filename..
  292.  
  293.   HighSecurity must be an integer, from 0 to 65535.
  294.  
  295.   The Colour options accept valid colour names or numbers.
  296.  
  297.   ╓─────────────────── Table of valid names and numbers ────────────────────╖
  298.   ╠════╤══════════╗╔════╤══════════════╗╔════╤════════════╗╔════╤═══════════╣
  299.   ║  0 │ Black    ║║  1 │ Blue         ║║  2 │ Green      ║║  3 │ Cyan      ║
  300.   ║  4 │ Red      ║║  5 │ Magenta      ║║  6 │ Brown      ║║  7 │ LightGray ║
  301.   ║  8 │ DarkGray ║║  9 │ LightBlue    ║║ 10 │ LightGreen ║║ 11 │ LightCyan ║
  302.   ║ 12 │ LightRed ║║ 13 │ LightMagenta ║║ 14 │ Yellow     ║║ 15 │ White     ║
  303.   ╠════╧══════════╝╚════╧══════════════╝╚════╧════════════╝╚════╧═══════════╣
  304.   ╙─────────────────────────────────────────────────────────────────────────╜
  305.  
  306.  
  307. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  308. │  3.3 │ The TOPFILE.EXC File ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  309. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  310.  
  311.   TOPFILE has the ability to use an external file of unwanted file names and
  312.   areas. It will use this list to filter out files and/or areas from the
  313.   'Top Downloaded Files' bulletins.
  314.  
  315.   The exclude file must be called 'TOPFILE.EXC' (without qoutes) and MUST be
  316.   located in the TOPFILE system directory (The directory you run TOPFILE
  317.   from.)
  318.  
  319.   TOPFILE.EXC is a plain ASCII text file, created with any text editor.
  320.   It has a specific format which is as follows:
  321.  
  322.   <exclusion type> <exclusion information>
  323.  
  324.   To exclude a file, the <exclusion type> is 'file' (no quotes, and any case)
  325.   and the <exclusion information> is the file name.
  326.  
  327.    Note:- There _MUST_ only be one file name per file exclusion line, and
  328.           the file name must have no spaces between the base name and the
  329.           extension. File names can be in any case but WILDCARDS ARE NOT
  330.           SUPPORTED.
  331.   
  332.    Examples:-  file ALLFILES.ZIP         is a valid file exclusion
  333.                file READ    .ME          is an invalid file exclusion
  334.                                             (This would be ignored)
  335.                READ.ME                   is an invalid exclude line
  336.                                             (This would be ignored)
  337.                READ    .ME               is invalid exclude line
  338.                                             (This would be ignored)
  339.  
  340.   To exclude a file area, the <exclusion type> is 'area' (no quotes, and any
  341.   case) and the <exclusion information> is the file area or you can specify
  342.   a range of areas to exclude thus <start file area>-<end file area>
  343.  
  344.    Note:- There _MUST_ only be one file area(s) exclusion per area exclusion
  345.           line, and if a range is specified there must be no spaces in the
  346.           definition of the range. Comma's in the area number(s) are not
  347.           tollerated.
  348.  
  349.    Examples:-  area 1                    is a valid single area exclusion
  350.                area 20-40                is a valid area range exclusion
  351.                area 40-20                is a valid area range exclusion, but
  352.                                             it would be converted to 20-40
  353.                area 20 - 40              is an invalid area range exclusion
  354.                1                         is an invalid exclusion line
  355.                                             (This would be ignored)
  356.                20-40                     is an invalid exclusion line
  357.                                             (This would be ignored)
  358.  
  359.   A sample Exclude file may look like this:
  360.   ----------------------------
  361.   file ALLFILES.ZIP
  362.   file ALLFILES.ARJ
  363.   file BBS_AD.ZIP
  364.   area 1
  365.   area 5
  366.   area 20-30
  367.   area 32-33
  368.   ----------------------------
  369.  
  370.   This would exclude any ALLFILES.ZIP, ALLFILES.ARJ and BBS_AD.ZIP files, and
  371.   exclude file areas 1, 5, 20 to 30 and 32 to 33.
  372.  
  373.  
  374. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  375. │  4.0 │ Bug Reports and Contacting the Author ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  376. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  377.  
  378.   Please contact me if you have any bug reports and/or suggestions for
  379.   improvements to TOPFILE.
  380.  
  381.   If you have a bug report, just mail a filled in REPORT.BUG (this file
  382.   should have been included in the distribution archive) to me at one of
  383.   the addresses below.
  384.  
  385.   I'm open to suggestions for support for other BBS software. If you wish
  386.   this please supply the structure of the filebase (and all related files)
  387.   files (PASCAL is prefered, but I can work with C) of the BBS you wish
  388.   supported (Also, could you give me a list of environment variables it
  389.   uses, and what they point to, ie RA points to the Remote Access system
  390.   directory, the config and filebase datafiles). I cannot guarantee it
  391.   will be supported, but you never know.
  392.  
  393.   I can be contacted using a number of different methods:
  394.  
  395.   Page/Leave a message on my BBS:
  396.    Virtual Maddness -- +44-1344-422575 -- 24 hours, 300 to 33600 baud
  397.  
  398.   Send a netmail to me at one of my various AKAs:
  399.    FidoNet    :  2:252/314
  400.    RANet      :  73:7441/13
  401.    PascalNet  :  115:4401/407
  402.    InterNet   :  dwayne@vmadd.demon.co.uk
  403.                  dwayne@roan.co.uk
  404.  
  405.  
  406. ╒══════╤══════════════════════════════════════════════════════════════════════╕
  407. │  5.0 │  Credits and Thanks ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  408. ╘══════╧══════════════════════════════════════════════════════════════════════╛
  409.  
  410.    Thanks to my beta testers for helping me test my progs and for their
  411.    numerous suggestions, helpful criticism and for the multitude of
  412.    bug reports.
  413.  
  414.    Thanks to Andrew Pappas, Michael Devonport and Peter Burnett for their
  415.    help with the Multi-Line BBS support.
  416.  
  417.    Thanks to Peter Burnett for supplying various bits of source code.
  418.  
  419.    Also thanks must go out to all the people who have sent suggestions
  420.    to me (Please keep it up), no names since you know who you are (actually
  421.    the list is too large to be included here)
  422.  
  423.  
  424.  Beta Testers
  425.  ============
  426.  
  427.    Steven Holme         The Fonty Towers BBS      +44-115-952-7443
  428.                         FidoNet    2:2503/216     +44-115-955-4440
  429.                                    2:2503/226
  430.                         RANet     73:7444/22
  431.  
  432.    Peter Burnett        Neverland eXpress         +44-1424-853361
  433.                         FidoNet    2:441/80
  434.                         RANet     73:7441/206
  435.  
  436.    Michael Devonport    Midnite Madness BBS       +44-181-287-5901
  437.                         FidoNet    2:254/301
  438.                         RANet     73:7441/15
  439.  
  440.    Simon Cansick        Guru-Ten BBS              +44-1535-691734
  441.                         FidoNet    2:250/364      +44-1535-691735
  442.                                    2:250/365
  443.                         RANet     73:7448/13
  444.  
  445.  
  446. ╒═════════════════════════════════════════════════════════════════════════════╕
  447. │ ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ End of File TOPFILE.DOC ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒ │
  448. ╘═════════════════════════════════════════════════════════════════════════════╛
  449.  
  450.