home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / MISC / TGFL_130.ZIP / TGFL.DOC < prev    next >
Text File  |  1998-07-01  |  19KB  |  466 lines
  1.  
  2.  
  3.  
  4.            Telegard File Lister Pro v1.30 Documentation
  5.          
  6.            Copyright (c) 1998 Dark Zone Software.
  7.            All rights reserved.
  8.  
  9.            File List Creater for Telegard bulletin board
  10.            software (BBS) v3.10 (3.09g?)
  11.  
  12.            Configuration and Reference Manual
  13.            Written by David Stumpf
  14.  
  15.            Dark Zone Software
  16.            7230 White Oak Circle
  17.            Houston, Texas 77040
  18.            USA
  19.  
  20.            Internet Email : David.Stumpf@Earthling.net
  21.            World Wide Web : http://www.dzs.home.ml.org
  22.  
  23.  
  24.  
  25.                       ────────────────────────────────────
  26.  
  27.                        BORING (BUT NECESSARY) LEGAL STUFF
  28.  
  29.                       ────────────────────────────────────
  30.  
  31.  
  32.  
  33.  
  34.    Warranty
  35.    ────────
  36.  
  37.       This  package is provided as-is, without warranty of any  kind,
  38.       either  expressed or implied, and is only guaranteed to  occupy
  39.       disk  space.  In no event will the author be liable to  you  or
  40.       anyone else for any damages, including (but not limited to) any
  41.       lost profits, lost savings or other incidental or consequential
  42.       damages  arising out of the use of, or inability to  use,  this
  43.       package.
  44.  
  45.       In short:  You're on your own.  If it works for you, great;  if
  46.       not,  or if it breaks something, c'est la vie.  As  the  saying
  47.       goes,  "Use it at your own risk, but if it breaks,  *YOU*  have
  48.       the pieces."
  49.  
  50.  
  51.  
  52.    Copyright Notice
  53.    ────────────────
  54.  
  55.      This package and all files contained herein are Copyright (c) 1998
  56.      by  Dark  Zone  Software.   No  modifications  may be made to  any
  57.      part  of this  program  and/or  package  without  express  written
  58.      permission  from  Dark  Zone  Software.     This  package  may  be
  59.      distributed in  any  medium  as long as the  following  conditions
  60.      are  met;  a)  The package  must  be  unmodified    b)  No fees of
  61.      any  kind  may be charged for this package or directly for  access
  62.      to this package.  This software may be distrubited by CD-ROM media
  63.      and/or "pay-only" system.
  64.  
  65.  
  66.  
  67.  
  68.    What it does
  69.    ────────────
  70.  
  71.    TGFL simply reads the Telegard file bases and creates a list of files
  72.    contained in them by using the parameters that you specify.
  73.  
  74.  
  75.  
  76.    Requirements
  77.    ────────────
  78.  
  79.      TGFL requires the following;
  80.  
  81.      100% IBM Compatible Computer
  82.      8086/88 or above CPU
  83.      MS-DOS v4.00 or Compatible
  84.      Telegard v3.10 (3.09x)
  85.  
  86.  
  87.  
  88.    Installation & Operation
  89.    ────────────────────────
  90.  
  91.    Just unarchive this package in to a directory of your choice.  I
  92.    suggest using your main bbs directory or a sub directory therein.
  93.  
  94.    If you place TGFL in any directory other than your main bbs directory
  95.    you must have a TELEGARD= or BBS= environment variable so TGFL can find
  96.    your CONFIG.TG file for operation.
  97.  
  98.    There are several files included in the archive, some of which are
  99.    optional and will not be used unless you specify to TGFL that you
  100.    wish it to use them.  For more information please check the
  101.    section labeled "Included Files".
  102.  
  103.    Now, you will need to decide what information that you want included
  104.    in your list file.  For this, either use the /? command line parameter
  105.    or refer to the section labeled "Operation".
  106.  
  107.  
  108.  
  109.    Included Files
  110.    ──────────────
  111.  
  112.    There are several file included in the original archive, below I
  113.    will list all of them and give a full explination of their purpose
  114.    and how to best use them.
  115.  
  116.    FILE_ID.DIZ   -  BBS Description file.
  117.  
  118.    TGFL.DOC      -  This documentation.
  119.  
  120.    TGFL.EXE      -  The main program file.
  121.  
  122.    TGFL.INC      -  This is the "Include" file, it contained a list of
  123.                     file areas to "Include" in the list file.  If this
  124.                     file is used, ONLY areas listed here will be displayed
  125.                     in the list file.
  126.  
  127.    TGFL.EXC      -  This is the "Exclude" file, it is similar to the
  128.                     Include file above.  It contains a list of area names
  129.                     to "Exclude" from the list.  If this file is used,
  130.                     the areas listed will NOT be added to the list file.
  131.                     This file can be used with or without the include
  132.                     file, although if both are used, you must remember
  133.                     that the Include list is checked first, then the
  134.                     exclude list.  So, if you have an area that is
  135.                     listed in BOTH files, it will NOT be listed.
  136.  
  137.    TGFL.HDR      -  This is the "Header" file.  If used, it will be
  138.                     attached to the very top of the list.  This file
  139.                     will usually contain information about the list
  140.                     file and/or bbs system.  For example, the bbs
  141.                     name, phone number and some extended information
  142.                     about the system may be contained in this file.
  143.                
  144.    TGFL.FTR      -  This is the "Footer" file.  If used, it will be
  145.                     attached to the very bottom of the list.  This file
  146.                     will usually contain information about the list
  147.                     and/or bbs as well.  The file can also be created
  148.                     by another utility to display a top downloader,
  149.                     uploaders, files, etc type of file.
  150.                
  151.    TGFL.CFG      -  This is an example config file.  It is much like
  152.                     an .INI file in it's format.  This file contains
  153.                     a list of options to use durring the operation
  154.                     of TGFL.  This file is read AFTER the command
  155.                     line is read.  So, if you turn something on
  156.                     via the command line, and turn it off via the
  157.                     config file, the option will be turned off.
  158.                     You do NOT have to list all options in this
  159.                     file, this example files shows how to "rem"
  160.                     things out, so they will not be read.  You can
  161.                     make multiple config files, one for each list
  162.                     that you wish to create.  Since the name is
  163.                     passed to TGFL on the command line, you can
  164.                     name them anything that you wish.
  165.  
  166.    HTML.HDR      -  This is an example header file for making an
  167.                     HTML style list file for use on the world
  168.                     wide web.  It can be used in place of the
  169.                     normal header file.
  170.  
  171.    HTML.FTR      -  This is an example footer file for making an
  172.                     HTML style list file for use on the world
  173.                     wide web.  It can be used in place of the
  174.                     normal footer file.
  175.  
  176.    MAKELIST.BAT  -  This example batch file for making an all
  177.                     files list and then zipping it up and placing
  178.                     it in the proper directory.
  179.  
  180.  
  181.  
  182.    Operation
  183.    ─────────
  184.  
  185.    The command line options are as follows;
  186.  
  187.    TGFL /? /# /B /CFG: /D /E /EXC: /FN /FTR: /HDR: /INC: /LST: /Nx
  188.         /O /S /TF /TI /TX /U /V
  189.  
  190.     - The /? option tells TGFL to display a help screen.  The help
  191.       screen will also be displayed if no command line parameters
  192.       are given.
  193.  
  194.     - The /# option tells TGFL to add the total number of downloads to
  195.       the list, below the description.
  196.  
  197.     - The /B option tells TGFL to add a blank line at the end of every
  198.       file description.  This allows each file to be seperated by a
  199.       blank line for easier reading.
  200.  
  201.     - The /CFG: option specifies a config or configuration file for
  202.       TGFL to use.  The config file can contain a number of options
  203.       and also makes it easier to configure multiple lists without
  204.       trying to get a command line just perfect.  The format for this
  205.       command is;
  206.  
  207.         TGFL /CFG:C:\DIR\TO\FILE\FILENAME.EXT
  208.  
  209.       The config file does NOT have to have any particular name OR
  210.       extension, as you must specify both on the command line, it
  211.       simply must be of the correct format.  (IE: plain text)
  212.  
  213.     - The /D option tells TGFL to add the date the file was uploaded to
  214.       the list below the description.
  215.  
  216.     - The /E option tells TGFL to display extended file information
  217.       after the file description.  This information tells wether
  218.       the file is a Free Download, Availible and wether or not it was
  219.       "Hatched" in to the file area.  This option ONLY works when
  220.       used with the /S option.
  221.  
  222.     - The /EXC: parameter specifies a path and filename to an Exclude
  223.       file, this file contains a list of file names of the file bases.
  224.       These names are simply listed one on each line.  For example;
  225.  
  226.         SYSOP
  227.         UPLOADS
  228.  
  229.       This will exclude the SYSOP and UPLOADS file areas from the
  230.       output file (file list).  This filename and possible the
  231.       path are specified the same way as the /CFG: command.
  232.  
  233.     - The /FN option tells TGFL to filter extra spaces out of file
  234.       names.  So a name like "TEST    .ZIP" now becomes "TEST.ZIP".
  235.       I saw mention that the other way isn't too awful friendly
  236.       to some mail readers such as TimEd.
  237.  
  238.     - The /FTR: option tells TGFL to use the specified FOOTER file.
  239.       This file is a basic ASCII (text) file that will be added
  240.       to the bottom of the output list file.
  241.  
  242.     - The /HDR: option tells TGFL to use the specified HEADER file.
  243.       This files is a basic ASCII (text) file that will be added
  244.       to the top of the output list file.
  245.  
  246.     - The /INC: parameter specifies a path and filename to an Include
  247.       file, this file contains a list of file names of the file bases.
  248.       These names are simply listed one on each line.  For example;
  249.  
  250.         GENERAL
  251.         TELEGARD
  252.  
  253.       This will include the GENERAL and TELEGARD file areas in the
  254.       output file (file list).  This filename and possible the
  255.       path are specified the same way as the /CFG: command.
  256.  
  257.       Rememver, if you specify an include file, ONLY the names
  258.       of the bases in this file will be in the output file.
  259.  
  260.     - The /LST: option specifies the path and filename to the
  261.       output file itself.  This is the file that will be created
  262.       by TGFL and will contain the list of files in your files
  263.       bases.  The path and filename are specified the same as
  264.       on the /CFG: option.
  265.  
  266.     - The /Nx option tells TGFL to list new files ONLY.  This is useful
  267.       when you want to create a list of new files that have been added
  268.       to your system recently.  You may optionally add a number ranging
  269.       between 0 and 9 after the N to denote the number of days old
  270.       an upload is before it is considered new.  The default age
  271.       is 5 days.
  272.  
  273.         NOTE:  The number zero (0) really means 10 days.
  274.  
  275.     - The /O option tells TGFL to append an "Overall Totals" area to
  276.       the bottom of the list with the total number of files and bytes
  277.       is all areas listed.
  278.  
  279.     - The /S option tells TGFL to add a "Status" line, under the file's
  280.       description telling wether or not the file is offline or online,
  281.       and if it is validated or not.
  282.  
  283.     - The /TF option tells TGFL to include a list of the top 10 overall
  284.       downloaded (i.e. most popular) files at the bottom of the output
  285.       list file.
  286.  
  287.     - The /TI option tells TGFL to include the time of day next to the
  288.       date, if it is included (/D).
  289.  
  290.     - The /TX option tells TGFL to make a basic text file which
  291.       contains no extended ASCII characters.  Very useful when
  292.       creating a list to be viewed on the www.
  293.  
  294.         NOTE: This option does NOT filter ANY extended
  295.               characters out of file descriptions.
  296.  
  297.     - The /U option tells TGFL to add the uploaders name to the list,
  298.       below the description.
  299.  
  300.     - The /V option tells TGFL to NOT list files which are not validated
  301.       for download by the users yet.
  302.  
  303.  
  304.  
  305.  
  306.    Special Thanks
  307.    ──────────────
  308.    Telegard Team - To all who make this, well, work.  Without
  309.                    you what would I write utilities for. . .
  310.  
  311.    Doug Reynolds - For the TGCOLOR.TPU code, this made the
  312.                    translation of the color codes possible.
  313.  
  314.    Tim Strike,
  315.    Scott Adams,
  316.    Lars Hellsten - For help with code and code concepts.
  317.  
  318.    Ken Reaverson
  319.       - and -
  320.    Mike Jackson  - For helping me beta test this software to
  321.                    make sure it is as bug free as possible.
  322.  
  323.  
  324.  
  325.  
  326.    Versions
  327.    ────────
  328.  
  329.             + Added     * Changed/Fixed   - Removed     ! Notes
  330.  
  331.  
  332.  
  333.                               v1.00
  334.  
  335.             ! First version.
  336.  
  337.  
  338.  
  339.                               v1.10
  340.  
  341.             + Added the /N command line parameter.  This
  342.               tells TGFL to list new files ONLY.
  343.             + Added some TG version checking code.
  344.             + Added file list totals on the screen, now
  345.               list total number of files and areas scanned
  346.               including time (number of seconds) that it
  347.               took to create the list.
  348.             + Added Color Code Filtering (Both `xx and |xx)
  349.               in file descriptions as well as area names.
  350.             + Now also translates TG color codes in the area
  351.               descriptions (on local display while processing).
  352.             + Added checking for the "TELEGARD=" environment
  353.               variable.  If found, it is used to find the
  354.               CONFIG.TG file if one does not exist in the
  355.               directory that TGFL is in.
  356.             + Added (/O) Overall Totals option.
  357.             * Spruced things up so they look a little better.
  358.               Added some color and such.
  359.             * Fixed bug which caused files to not be listed
  360.               if there was no description.
  361.             * You can now use the "-" delimiter as well as "/"
  362.               for command line options.
  363.             * Fixed bug which caused the ignore list not to work
  364.               properly. (Causes by a last minute change, sorry
  365.               folks.)
  366.             * The "/ver" command line option is no longer case
  367.               sensitive.
  368.  
  369.  
  370.  
  371.                               v1.11
  372.  
  373.             * Now filters the display of empty file bases.
  374.             * Description are now seperated with a CR/LF
  375.               instead of just a CR.  (Thanks Lars)
  376.             * Now excepts command line like;
  377.               (TGFL FILES.LST /#/d/o) with no spaces
  378.               between the options.
  379.             ! Minor bug fix over 1.10, which most folks
  380.               never saw.
  381.             ! TGFL currently chops the file descriptions at 45
  382.               characters MAX.  I'll see what I can do about
  383.               this in the future.
  384.  
  385.  
  386.  
  387.                               v1.20
  388.  
  389.             + Added /TX option, which produces a simplified
  390.               ascii file similar to a FILES.BBS file.
  391.             + Added status bars.
  392.             * Now supports over 2gigs of files in listing.
  393.               (limit should now be roughly 2,147 gigs)
  394.             * Help screen is now displayed if no command line
  395.               is passed.
  396.             * Changed the local display around again.  ;}
  397.             * Blank line between descriptions is now optional
  398.               via the /B command line option.
  399.             * Filenames can now optionally have the spaces removed
  400.               to be more friendly to things like TimEd.
  401.             * The /T command line has been changed to /TI.
  402.             * You may now, optionally, specify the number of
  403.               days old a file needs to be to be considered
  404.               new.  Days range from 1 to 10.
  405.             * Fixed bug which caused the description to be
  406.               separated by a spare line if the extended
  407.               file stats were included.
  408.             * Re-wrote unix date code with some help from
  409.               SWAG donators.
  410.             * Fixed Pentium II (200mhz+) bug.
  411.             * Fixed bug which caused TG not to find .FA/.FAD
  412.               files if they were in a path other than the
  413.               default file path.
  414.  
  415.  
  416.  
  417.                               v1.21
  418.  
  419.             * Fixed minor output bug which put the wrong title
  420.               line above the file area stats on a text list
  421.               when the overall totals were added.
  422.             * I did some work on the description reading
  423.               code.  All tests I have done show it to be
  424.               only slightly faster, but, it should be
  425.               more stable now.
  426.             * Fixed bug that caused TGFL to freeze up some
  427.               times if a description ended in a color code.
  428.               IE (Whatever`70) but not (Whatever`70{CR}{LF}).
  429.  
  430.  
  431.  
  432.                               v1.30
  433.  
  434.             + Added a config file.
  435.             + Added top files (downloads) list.  (/TF)
  436.             + Added the include/exclude/header/footer file
  437.               names to the main screen so you know which ones
  438.               TGFL is using.
  439.             + TGFL now checks the environment for BBS= as well
  440.               as TELEGARD= in order to find the CONFIG.TG.
  441.             - Removed the default search for the exclude file.
  442.               This file must now either be specified on the command
  443.               line or via the config file.
  444.             * Fixed bug which removed the spaces from
  445.               file base headers in TEXT (/TX) mode.
  446.             * Removed the odd number from the local display
  447.               when TGFL was finished.  My appologies, it was
  448.               some debug code.
  449.             * Fixed bug which caused some descriptions (actually
  450.               most) to be ended with a blank line.  This was
  451.               caused by the new description reading code.
  452.             * The output file name on the command line has been
  453.               changed, it is no longer the first parameter, it
  454.               must now be specified via a command line switch.
  455.               This was done because of the command line changes
  456.               for the new config file.
  457.             * Worked on the error checking code some.  Fixed one
  458.               bug and made some changes to make it easier to know
  459.               what happened.
  460.             * Fixed visual bug which caused the name of the file
  461.               being processed to be right justified instead of left
  462.               justified if the filter spaces option is used.
  463.             - Removed the default search for the TGFL.HDR and
  464.               TGFL.FTR files, they are now passed via the command
  465.               line or config file.
  466.